ralph/queue/
operations.rs

1//! Task queue task-level operations.
2//!
3//! Responsibilities:
4//! - Mutate or query tasks within queue files (complete tasks, set statuses/fields, find tasks, delete tasks, sort by priority).
5//! - Provide typed domain errors for queue query operations to enable stable test assertions.
6//!
7//! Does not handle:
8//! - Persisting queue data or managing locks (load/save/locks/repair live in `crate::queue`).
9//! - Task-level validation beyond runnability checks (see `validate` module for schema-level validation).
10//!
11//! Invariants/assumptions:
12//! - Queue operations are called with fully loaded `QueueFile` values.
13//! - Queue query errors are returned as `anyhow::Result` but wrap typed `QueueQueryError` for downcasting in tests.
14//! - Message text in `QueueQueryError` variants must match user-facing expectations (single source of truth).
15
16mod archive;
17mod batch;
18mod edit;
19mod fields;
20mod mutation;
21mod query;
22mod runnability;
23mod status;
24mod validate;
25
26pub use archive::*;
27pub use batch::*;
28pub use edit::*;
29pub use fields::*;
30pub use mutation::*;
31pub use query::*;
32pub use runnability::*;
33pub use status::*;
34
35#[cfg(test)]
36#[path = "operations/tests/mod.rs"]
37mod tests;
38
39use crate::contracts::TaskStatus;
40use crate::error_messages::task_not_found_with_operation;
41
42#[derive(Debug, thiserror::Error)]
43pub enum QueueQueryError {
44    #[error(
45        "Queue query failed (operation={operation}): missing target_task_id. Example: --target RQ-0001."
46    )]
47    MissingTargetTaskId { operation: String },
48
49    #[error("{}", task_not_found_with_operation(operation, task_id))]
50    TargetTaskNotFound { operation: String, task_id: String },
51
52    #[error(
53        "Queue query failed (operation={operation}): target task {task_id} is not runnable (status: {status}). Choose a todo/doing task."
54    )]
55    TargetTaskNotRunnable {
56        operation: String,
57        task_id: String,
58        status: TaskStatus,
59    },
60
61    #[error(
62        "Queue query failed (operation={operation}): target task {task_id} is in draft status. Use --include-draft to run draft tasks."
63    )]
64    TargetTaskDraftExcluded { operation: String, task_id: String },
65
66    #[error(
67        "Queue query failed (operation={operation}): target task {task_id} is blocked by unmet dependencies. Resolve dependencies before running."
68    )]
69    TargetTaskBlockedByUnmetDependencies { operation: String, task_id: String },
70
71    #[error(
72        "Queue query failed (operation={operation}): target task {task_id} is scheduled for the future ({scheduled_start}). Wait until the scheduled time."
73    )]
74    TargetTaskScheduledForFuture {
75        operation: String,
76        task_id: String,
77        scheduled_start: String,
78    },
79}
ralph/queue/operations.rs

ralph/queue/
operations.rs
