onetaskgraph_core/engine/local.rs
1//! The predicates the engine applies itself, over the wider set a source returned.
2//!
3//! Every function here runs only for a predicate the source declared
4//! [`Unsupported`](onetaskgraph_plugin_api::Support::Unsupported), which is the engine's
5//! side of the contract — rule 3. What makes narrowing here sound is the source's side,
6//! rule 2: a source *ignores* such a predicate and returns the wider set. So the rows
7//! this drops are rows the caller asked not to see, and the rows it keeps are all the
8//! rows there were. A source that narrowed for a predicate it declared unsupported would
9//! break rule 2, and nothing above the plugin could tell.
10//!
11//! This is not a copy of a plugin's filtering for the sake of it. A source that applies
12//! a predicate natively never reaches this code, and a plugin's own evaluation is behind
13//! its own crate boundary — the engine may not reach into one, and the moment it did,
14//! the answer would depend on which plugin happened to be first in the list.
15
16use onetaskgraph_plugin_api::{
17 Document, Label, LabelFilter, NativeId, Project, ProjectFilter, StatusCategory, Task,
18 TextFields, TextQuery,
19};
20
21/// The task predicates this source left to the engine.
22///
23/// Each field is `None`/empty when the source applied that predicate itself, so a
24/// filter built from a fully native source keeps everything and costs one comparison
25/// per row.
26#[derive(Debug, Clone, Default, PartialEq)]
27pub(crate) struct LocalTasks {
28 /// Label membership, when the source does not filter by label.
29 pub labels: Option<LabelFilter>,
30 /// Status categories, when the source does not filter by status.
31 pub statuses: Vec<StatusCategory>,
32 /// Free text, when the source does not search every field the query names.
33 pub text: Option<TextQuery>,
34 /// The owning project, when the source does not filter by it.
35 pub project: Option<ProjectFilter>,
36}
37
38impl LocalTasks {
39 /// Whether `task` survives every predicate left to the engine.
40 pub fn keeps(&self, task: &Task) -> bool {
41 if let Some(filter) = &self.labels
42 && !labels_match(&task.labels, filter)
43 {
44 return false;
45 }
46 if !status_matches(task.status.category, &self.statuses) {
47 return false;
48 }
49 if let Some(query) = &self.text
50 && !text_matches(&task.title, task.content.as_deref(), query)
51 {
52 return false;
53 }
54 match &self.project {
55 None | Some(ProjectFilter::Any) => true,
56 Some(ProjectFilter::Orphans) => task.project.is_none(),
57 Some(ProjectFilter::Is(id)) => task.project.as_ref() == Some(id),
58 }
59 }
60}
61
62/// The project predicates this source left to the engine.
63#[derive(Debug, Clone, Default, PartialEq)]
64pub(crate) struct LocalProjects {
65 /// Label membership, when the source does not filter by label.
66 pub labels: Option<LabelFilter>,
67 /// Status categories, when the source does not filter by status.
68 pub statuses: Vec<StatusCategory>,
69 /// Free text, when the source does not search every field the query names.
70 pub text: Option<TextQuery>,
71}
72
73impl LocalProjects {
74 /// Whether `project` survives every predicate left to the engine.
75 pub fn keeps(&self, project: &Project) -> bool {
76 if let Some(filter) = &self.labels
77 && !labels_match(&project.labels, filter)
78 {
79 return false;
80 }
81 if !status_matches(project.status.category, &self.statuses) {
82 return false;
83 }
84 match &self.text {
85 None => true,
86 Some(query) => text_matches(&project.title, project.content.as_deref(), query),
87 }
88 }
89}
90
91/// The document predicates this source left to the engine.
92///
93/// No statuses, deliberately: a document is not work and carries none, so a status filter
94/// has nothing here to compare against.
95#[derive(Debug, Clone, Default, PartialEq)]
96pub(crate) struct LocalDocuments {
97 /// Label membership, when the source does not filter by label.
98 pub labels: Option<LabelFilter>,
99 /// Free text, when the source does not search every field the query names.
100 pub text: Option<TextQuery>,
101 /// The owning project, when the source does not filter by it.
102 pub project: Option<ProjectFilter>,
103}
104
105impl LocalDocuments {
106 /// Whether `document` survives every predicate left to the engine.
107 pub fn keeps(&self, document: &Document) -> bool {
108 if let Some(filter) = &self.labels
109 && !labels_match(&document.labels, filter)
110 {
111 return false;
112 }
113 if let Some(query) = &self.text
114 && !text_matches(&document.title, document.content.as_deref(), query)
115 {
116 return false;
117 }
118 match &self.project {
119 None | Some(ProjectFilter::Any) => true,
120 Some(ProjectFilter::Orphans) => document.project.is_none(),
121 Some(ProjectFilter::Is(id)) => document.project.as_ref() == Some(id),
122 }
123 }
124}
125
126/// Whether `labels` satisfies `filter`, matching by name, case-insensitively.
127///
128/// By name rather than by id because a label id is per-source and a user filtering
129/// across sources types a word — the reason [`LabelFilter`] is spelled in names at all.
130pub(crate) fn labels_match(labels: &[Label], filter: &LabelFilter) -> bool {
131 let held: Vec<String> = labels
132 .iter()
133 .map(|label| label.name.to_lowercase())
134 .collect();
135 let holds = |name: &String| held.contains(&name.to_lowercase());
136
137 if !filter.any_of.is_empty() && !filter.any_of.iter().any(holds) {
138 return false;
139 }
140 if !filter.all_of.iter().all(holds) {
141 return false;
142 }
143 !filter.none_of.iter().any(holds)
144}
145
146/// An empty list is unfiltered rather than "keeps nothing", which is what makes
147/// `statuses: Vec<StatusCategory>` able to spell "no status filter at all".
148pub(crate) fn status_matches(category: StatusCategory, statuses: &[StatusCategory]) -> bool {
149 statuses.is_empty() || statuses.contains(&category)
150}
151
152/// Whether `title`/`content` satisfies `query`, matching case-insensitively.
153pub(crate) fn text_matches(title: &str, content: Option<&str>, query: &TextQuery) -> bool {
154 let terms = query.terms.to_lowercase();
155 let in_title = title.to_lowercase().contains(&terms);
156 let in_content = content.is_some_and(|body| body.to_lowercase().contains(&terms));
157 match query.fields {
158 TextFields::Title => in_title,
159 TextFields::Content => in_content,
160 TextFields::TitleOrContent => in_title || in_content,
161 }
162}
163
164/// Which project a task must belong to, as a command line names it.
165///
166/// Qualified (`work:PROJ-1`) or bare (`PROJ-1`), because both are things a user types
167/// and they mean different queries: a qualified id names one project of one source and
168/// restricts the query to it, while a bare one is a native id every selected source is
169/// asked about. Which of the two a string is depends on whether its prefix names a
170/// **configured source**, so a native id full of colons is still a native id.
171#[derive(Debug, Clone, Default, PartialEq, Eq)]
172pub enum ProjectSelector {
173 /// No constraint.
174 #[default]
175 Any,
176 /// Only tasks belonging to no project at all.
177 Orphans,
178 /// One project of one source.
179 Qualified(crate::GlobalId),
180 /// A native id, asked of every selected source.
181 Native(NativeId),
182}