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 transaction;
25mod validate;
26
27pub use archive::*;
28pub use batch::*;
29pub use edit::*;
30pub use fields::*;
31pub use mutation::*;
32pub use query::*;
33pub use runnability::*;
34pub use status::*;
35pub use transaction::*;
36
37#[cfg(test)]
38#[path = "operations/tests/mod.rs"]
39mod tests;
40
41use crate::contracts::TaskStatus;
42use crate::error_messages::task_not_found_with_operation;
43
44#[derive(Debug, thiserror::Error)]
45pub enum QueueQueryError {
46    #[error(
47        "Queue query failed (operation={operation}): missing target_task_id. Example: --target RQ-0001."
48    )]
49    MissingTargetTaskId { operation: String },
50
51    #[error("{}", task_not_found_with_operation(operation, task_id))]
52    TargetTaskNotFound { operation: String, task_id: String },
53
54    #[error(
55        "Queue query failed (operation={operation}): target task {task_id} is not runnable (status: {status}). Choose a todo/doing task."
56    )]
57    TargetTaskNotRunnable {
58        operation: String,
59        task_id: String,
60        status: TaskStatus,
61    },
62
63    #[error(
64        "Queue query failed (operation={operation}): target task {task_id} is in draft status. Use --include-draft to run draft tasks."
65    )]
66    TargetTaskDraftExcluded { operation: String, task_id: String },
67
68    #[error(
69        "Queue query failed (operation={operation}): target task {task_id} is blocked by unmet dependencies. Resolve dependencies before running."
70    )]
71    TargetTaskBlockedByUnmetDependencies { operation: String, task_id: String },
72
73    #[error(
74        "Queue query failed (operation={operation}): target task {task_id} is scheduled for the future ({scheduled_start}). Wait until the scheduled time."
75    )]
76    TargetTaskScheduledForFuture {
77        operation: String,
78        task_id: String,
79        scheduled_start: String,
80    },
81}
ralph/queue/operations.rs

ralph/queue/
operations.rs
