jot_core/
storage.rs

1// Copyright (c) 2026 Joydev GmbH (joydev.com)
2// SPDX-License-Identifier: MIT
3
4//! Workspace storage for jot.
5//!
6//! Jot reuses joy-core's generic YAML primitives (`store::write_yaml`,
7//! `store::read_yaml`) and ID helpers (`item_filename`, `title_hash_suffix`)
8//! to operate on `.jot/` without duplicating IO logic or requiring changes
9//! to joy-core. See `docs/dev/Architecture.md`.
10
11use std::path::{Path, PathBuf};
12
13use joy_core::items::title_hash_suffix;
14use joy_core::model::item::item_filename;
15use joy_core::store::{read_yaml, write_yaml};
16
17use crate::error::JotError;
18use crate::model::Task;
19
20pub const JOT_DIR: &str = ".jot";
21pub const ITEMS_DIR: &str = "items";
22pub const ACRONYM: &str = "TODO";
23
24pub fn jot_dir(root: &Path) -> PathBuf {
25    root.join(JOT_DIR)
26}
27
28pub fn items_dir(root: &Path) -> PathBuf {
29    jot_dir(root).join(ITEMS_DIR)
30}
31
32/// Create `.jot/items/` if missing. Idempotent.
33pub fn ensure_items_dir(root: &Path) -> Result<(), JotError> {
34    let dir = items_dir(root);
35    std::fs::create_dir_all(&dir)
36        .map_err(|e| JotError::Other(format!("cannot create {}: {}", dir.display(), e)))
37}
38
39/// Write a task to `.jot/items/{ID}-{slug}.yaml`.
40pub fn save_task(root: &Path, task: &Task) -> Result<(), JotError> {
41    ensure_items_dir(root)?;
42    let filename = item_filename(&task.item.id, &task.item.title);
43    let path = items_dir(root).join(filename);
44    write_yaml(&path, task)?;
45    Ok(())
46}
47
48/// Load all tasks from `.jot/items/`, sorted by filename.
49pub fn load_tasks(root: &Path) -> Result<Vec<Task>, JotError> {
50    let dir = items_dir(root);
51    if !dir.is_dir() {
52        return Ok(Vec::new());
53    }
54    let mut entries: Vec<_> = std::fs::read_dir(&dir)
55        .map_err(|e| JotError::Other(format!("cannot read {}: {}", dir.display(), e)))?
56        .filter_map(|e| e.ok())
57        .filter(|e| {
58            e.path()
59                .extension()
60                .is_some_and(|ext| ext == "yaml" || ext == "yml")
61        })
62        .collect();
63    entries.sort_by_key(|e| e.file_name());
64
65    let mut tasks = Vec::with_capacity(entries.len());
66    for entry in entries {
67        let task: Task = read_yaml(&entry.path())?;
68        tasks.push(task);
69    }
70    Ok(tasks)
71}
72
73/// Find the file for a task ID, accepting full or short form.
74/// Returns an error if the ID is ambiguous or missing.
75pub fn find_task_file(root: &Path, id: &str) -> Result<PathBuf, JotError> {
76    let dir = items_dir(root);
77    if !dir.is_dir() {
78        return Err(JotError::Other(format!("task not found: {id}")));
79    }
80    let id_upper = id.to_uppercase();
81    let prefix = format!("{id_upper}-");
82
83    let matches: Vec<PathBuf> = std::fs::read_dir(&dir)
84        .map_err(|e| JotError::Other(format!("cannot read {}: {}", dir.display(), e)))?
85        .filter_map(|e| e.ok())
86        .map(|e| e.path())
87        .filter(|p| {
88            p.file_name()
89                .map(|n| n.to_string_lossy().to_uppercase().starts_with(&prefix))
90                .unwrap_or(false)
91        })
92        .collect();
93
94    match matches.len() {
95        0 => Err(JotError::Other(format!("task not found: {id}"))),
96        1 => Ok(matches.into_iter().next().unwrap()),
97        _ => Err(JotError::Other(format!(
98            "ambiguous ID {id}: {} matches",
99            matches.len()
100        ))),
101    }
102}
103
104/// Delete a task by ID. Returns the deleted task.
105pub fn delete_task(root: &Path, id: &str) -> Result<Task, JotError> {
106    let path = find_task_file(root, id)?;
107    let task: Task = read_yaml(&path)?;
108    std::fs::remove_file(&path)
109        .map_err(|e| JotError::Other(format!("cannot remove {}: {}", path.display(), e)))?;
110    Ok(task)
111}
112
113/// Generate the next ID in the form `TODO-XXXX-YY` (ADR-027).
114pub fn next_id(root: &Path, title: &str) -> Result<String, JotError> {
115    let suffix = title_hash_suffix(title);
116    let dir = items_dir(root);
117    if !dir.is_dir() {
118        return Ok(format!("{ACRONYM}-0001-{suffix}"));
119    }
120
121    let prefix = format!("{ACRONYM}-");
122    let mut max_num: u16 = 0;
123    for entry in std::fs::read_dir(&dir)
124        .map_err(|e| JotError::Other(format!("cannot read {}: {}", dir.display(), e)))?
125        .filter_map(|e| e.ok())
126    {
127        let name = entry.file_name();
128        let name = name.to_string_lossy();
129        if let Some(rest) = name.strip_prefix(&prefix) {
130            if let Some(hex) = rest.get(..4) {
131                if let Ok(n) = u16::from_str_radix(hex, 16) {
132                    max_num = max_num.max(n);
133                }
134            }
135        }
136    }
137
138    let next = max_num.checked_add(1).ok_or_else(|| {
139        JotError::Other(format!("{ACRONYM} ID space exhausted (max {ACRONYM}-FFFF)"))
140    })?;
141    Ok(format!("{ACRONYM}-{next:04X}-{suffix}"))
142}
143
144#[cfg(test)]
145mod tests {
146    use super::*;
147    use tempfile::tempdir;
148
149    fn make_task(id: &str, title: &str) -> Task {
150        Task::new(id.into(), title.into())
151    }
152
153    #[test]
154    fn next_id_first_in_empty_dir() {
155        let dir = tempdir().unwrap();
156        let id = next_id(dir.path(), "Buy milk").unwrap();
157        assert!(id.starts_with("TODO-0001-"), "got: {id}");
158        assert_eq!(id.len(), 12);
159    }
160
161    #[test]
162    fn next_id_increments_after_save() {
163        let dir = tempdir().unwrap();
164        let t1 = make_task("TODO-0001-A3", "First");
165        save_task(dir.path(), &t1).unwrap();
166        let id2 = next_id(dir.path(), "Second").unwrap();
167        assert!(id2.starts_with("TODO-0002-"), "got: {id2}");
168    }
169
170    #[test]
171    fn save_then_load_roundtrip() {
172        let dir = tempdir().unwrap();
173        let id = next_id(dir.path(), "Buy milk").unwrap();
174        let task = make_task(&id, "Buy milk");
175        save_task(dir.path(), &task).unwrap();
176        let loaded = load_tasks(dir.path()).unwrap();
177        assert_eq!(loaded.len(), 1);
178        assert_eq!(loaded[0].item.id, id);
179        assert_eq!(loaded[0].item.title, "Buy milk");
180    }
181
182    #[test]
183    fn load_tasks_empty_returns_empty() {
184        let dir = tempdir().unwrap();
185        let loaded = load_tasks(dir.path()).unwrap();
186        assert!(loaded.is_empty());
187    }
188
189    #[test]
190    fn delete_removes_file() {
191        let dir = tempdir().unwrap();
192        let id = next_id(dir.path(), "Temp").unwrap();
193        let task = make_task(&id, "Temp");
194        save_task(dir.path(), &task).unwrap();
195        let deleted = delete_task(dir.path(), &id).unwrap();
196        assert_eq!(deleted.item.id, id);
197        assert!(load_tasks(dir.path()).unwrap().is_empty());
198    }
199
200    #[test]
201    fn find_task_file_short_form() {
202        let dir = tempdir().unwrap();
203        let id = next_id(dir.path(), "Short form").unwrap();
204        let task = make_task(&id, "Short form");
205        save_task(dir.path(), &task).unwrap();
206        let short = &id[..9]; // "TODO-0001"
207        let path = find_task_file(dir.path(), short).unwrap();
208        assert!(path
209            .file_name()
210            .unwrap()
211            .to_string_lossy()
212            .starts_with(short));
213    }
214
215    #[test]
216    fn find_task_file_missing_errors() {
217        let dir = tempdir().unwrap();
218        ensure_items_dir(dir.path()).unwrap();
219        let err = find_task_file(dir.path(), "TODO-9999");
220        assert!(err.is_err());
221    }
222}
jot_core/storage.rs

jot_core/
storage.rs
