use super::*;
use crate::memory::{
finding_status, FINDING_BODY_MAX, FINDING_CATEGORIES, FINDING_PRIORITIES, FINDING_TITLE_MAX,
FINDING_TRANSITIONS, MNEMO_META_BATCH, MNEMO_META_CATEGORY, MNEMO_META_FINDING_ID,
MNEMO_META_KIND_FINDING, MNEMO_META_PRIORITY, MNEMO_META_TRIAGE, MNEMO_META_TRIAGED_BY,
MNEMO_META_VERIFIED_BY, MNEMO_META_VERIFIED_REF,
};
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FindingSpec {
pub id: String,
pub category: String,
pub priority: String,
pub title: String,
pub body: String,
pub refs: Vec<String>,
}
#[derive(Debug, Clone, PartialEq)]
pub struct Finding {
pub record_id: Ulid,
pub id: String,
pub batch: String,
pub category: String,
pub priority: String,
pub title: String,
pub body: String,
pub refs: Vec<String>,
pub author: Option<String>,
pub status: String,
pub triage: Option<String>,
pub triaged_by: Option<String>,
pub verified_ref: Option<String>,
pub verified_by: Option<String>,
pub created_at: i64,
pub history: Vec<Value>,
}
impl Finding {
pub fn from_memory(m: &Memory) -> Option<Finding> {
if m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) != Some(MNEMO_META_KIND_FINDING)
{
return None;
}
let s = |k: &str| {
m.metadata
.get(k)
.and_then(Value::as_str)
.map(str::to_string)
};
let (title, body) = match m.content.split_once("\n\n") {
Some((a, b)) => (a.to_string(), b.to_string()),
None => (m.content.clone(), String::new()),
};
Some(Finding {
record_id: m.id,
id: s(MNEMO_META_FINDING_ID).unwrap_or_default(),
batch: s(MNEMO_META_BATCH).unwrap_or_default(),
category: s(MNEMO_META_CATEGORY).unwrap_or_default(),
priority: s(MNEMO_META_PRIORITY).unwrap_or_default(),
title,
body,
refs: m
.metadata
.get(crate::memory::MNEMO_META_REFS)
.and_then(Value::as_array)
.map(|a| {
a.iter()
.filter_map(|v| v.as_str().map(str::to_string))
.collect()
})
.unwrap_or_default(),
author: s(crate::memory::MNEMO_META_AUTHOR),
status: s(MNEMO_META_STATUS).unwrap_or_default(),
triage: s(MNEMO_META_TRIAGE),
triaged_by: s(MNEMO_META_TRIAGED_BY),
verified_ref: s(MNEMO_META_VERIFIED_REF),
verified_by: s(MNEMO_META_VERIFIED_BY),
created_at: m.created_at,
history: m
.metadata
.get(MNEMO_META_STATUS_HISTORY)
.and_then(Value::as_array)
.cloned()
.unwrap_or_default(),
})
}
pub fn sort_key(&self) -> (String, u64, u64) {
parse_id(&self.id).unwrap_or((self.id.clone(), 0, 0))
}
}
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct FindingFilter {
pub status: Option<String>,
pub batch: Option<String>,
pub category: Option<String>,
pub priority: Option<String>,
}
fn parse_id(id: &str) -> Option<(String, u64, u64)> {
let (prefix, rest) = id.split_once('-')?;
let (a, b) = rest.split_once('.')?;
let digits = |s: &str| !s.is_empty() && s.bytes().all(|c| c.is_ascii_digit());
if prefix.is_empty()
|| !prefix.bytes().all(|c| c.is_ascii_uppercase())
|| !digits(a)
|| !digits(b)
{
return None;
}
Some((prefix.to_string(), a.parse().ok()?, b.parse().ok()?))
}
pub fn valid_finding_id(id: &str) -> bool {
id.len() <= 64 && parse_id(id).is_some()
}
const SECURITY: &str = "SECURITY";
fn is_release_tag(r: &str) -> bool {
let Some(rest) = r.strip_prefix('v') else {
return false;
};
let parts: Vec<&str> = rest.split('.').collect();
parts.len() == 3
&& parts
.iter()
.all(|p| !p.is_empty() && p.bytes().all(|c| c.is_ascii_digit()))
}
pub(super) fn is_finding(m: &Memory) -> bool {
m.metadata.get(MNEMO_META_KIND).and_then(Value::as_str) == Some(MNEMO_META_KIND_FINDING)
}
pub(super) fn finding_write_refused(what: &str) -> MnemoError {
MnemoError::Invalid(format!(
"a finding can't be {what}: it changes only by `finding triage` or `finding verify`; \
a wrong one is rejected, with why, which keeps its history"
))
}
fn batch_of(id: &str) -> String {
id.rsplit_once('.').map_or(id, |(b, _)| b).to_string()
}
impl Mnemo {
fn finding_records(&mut self, id: Option<&str>) -> Result<Vec<Memory>> {
self.coordination_records(MNEMO_META_KIND_FINDING, id)
}
fn finding_record(&mut self, id: &str) -> Result<Option<Memory>> {
Ok(self
.finding_records(Some(id))?
.into_iter()
.find(|m| Finding::from_memory(m).is_some_and(|f| f.id == id)))
}
pub fn finding(&mut self, id: &str) -> Result<Option<Finding>> {
Ok(self
.finding_record(id)?
.as_ref()
.and_then(Finding::from_memory))
}
pub fn findings(&mut self, filter: &FindingFilter) -> Result<Vec<Finding>> {
let eq = |want: &Option<String>, have: &str| want.as_deref().is_none_or(|w| w == have);
let mut v: Vec<Finding> = self
.finding_records(None)?
.iter()
.filter_map(Finding::from_memory)
.filter(|f| {
eq(&filter.status, &f.status)
&& eq(&filter.batch, &f.batch)
&& eq(&filter.category, &f.category)
&& eq(&filter.priority, &f.priority)
})
.collect();
v.sort_by_key(Finding::sort_key);
Ok(v)
}
pub fn finding_add(&mut self, spec: &FindingSpec) -> Result<Finding> {
if self.read_only {
return Err(MnemoError::ReadOnly);
}
if self.author.as_deref().is_none_or(|a| a.trim().is_empty()) {
return Err(MnemoError::Invalid(
"a finding needs its author: name the agent (MNEMO_AGENT, or --as on the CLI)"
.into(),
));
}
if !valid_finding_id(&spec.id) {
return Err(MnemoError::Invalid(format!(
"{:?} isn't a finding's id: capital letters, '-', a number, '.', a number \
(RB-014.1)",
spec.id
)));
}
if !FINDING_CATEGORIES.contains(&spec.category.as_str()) {
return Err(MnemoError::Invalid(format!(
"{:?} isn't a category: {}",
spec.category,
FINDING_CATEGORIES.join(", ")
)));
}
if !FINDING_PRIORITIES.contains(&spec.priority.as_str()) {
return Err(MnemoError::Invalid(format!(
"{:?} isn't a priority: {}",
spec.priority,
FINDING_PRIORITIES.join(", ")
)));
}
let title = spec.title.trim();
if title.is_empty() || title.contains('\n') || title.len() > FINDING_TITLE_MAX {
return Err(MnemoError::Invalid(format!(
"a finding's title is one line, not empty, at most {FINDING_TITLE_MAX} bytes"
)));
}
if spec.body.len() > FINDING_BODY_MAX {
return Err(MnemoError::Invalid(format!(
"a finding's body is at most {FINDING_BODY_MAX} bytes"
)));
}
let want = parse_id(&spec.id);
if let Some(taken) = self
.finding_records(None)?
.iter()
.filter_map(Finding::from_memory)
.find(|f| f.id == spec.id || parse_id(&f.id) == want)
{
let same = if taken.id == spec.id {
String::new()
} else {
format!(" (as {})", taken.id)
};
return Err(MnemoError::Invalid(format!(
"{} is taken{same}; give the next free id",
spec.id
)));
}
let content = if spec.body.is_empty() {
title.to_string()
} else {
format!("{title}\n\n{}", spec.body)
};
let mut meta = Map::new();
meta.insert(MNEMO_META_FINDING_ID.into(), Value::String(spec.id.clone()));
meta.insert(MNEMO_META_BATCH.into(), Value::String(batch_of(&spec.id)));
meta.insert(
MNEMO_META_CATEGORY.into(),
Value::String(spec.category.clone()),
);
meta.insert(
MNEMO_META_PRIORITY.into(),
Value::String(spec.priority.clone()),
);
meta.insert(
MNEMO_META_STATUS.into(),
Value::String(finding_status::OPEN.into()),
);
meta.insert(
crate::memory::MNEMO_META_REFS.into(),
Value::Array(spec.refs.iter().map(|r| Value::String(r.clone())).collect()),
);
if spec.category == SECURITY {
meta.insert(
crate::memory::MNEMO_META_VISIBILITY.into(),
Value::String("private".into()),
);
}
let id =
self.put_coordination_with_id(Ulid::new(), MNEMO_META_KIND_FINDING, content, meta)?;
Ok(Finding::from_memory(&self.get(&id)?).expect("a finding"))
}
pub fn finding_triage(&mut self, id: &str, to: &str, text: &str) -> Result<Finding> {
if to == finding_status::VERIFIED {
return Err(MnemoError::Invalid(
"a finding is verified with `verify`, and a ref".into(),
));
}
let text = text.trim();
if text.is_empty() || text.len() > FINDING_BODY_MAX {
return Err(MnemoError::Invalid(format!(
"a triage needs its text (why), at most {FINDING_BODY_MAX} bytes"
)));
}
self.finding_move(id, to, text, |m, by| {
m.metadata
.insert(MNEMO_META_TRIAGE.into(), Value::String(text.to_string()));
m.metadata
.insert(MNEMO_META_TRIAGED_BY.into(), Value::String(by.to_string()));
})
}
pub fn finding_verify(&mut self, id: &str, verified_ref: &str) -> Result<Finding> {
let r = verified_ref.trim();
if r.is_empty() || r.contains('\n') || r.len() > FINDING_TITLE_MAX {
return Err(MnemoError::Invalid(format!(
"a verification needs its ref (a commit, a tag, a PR), one line, at most \
{FINDING_TITLE_MAX} bytes"
)));
}
let security = self.finding(id)?.is_some_and(|f| f.category == SECURITY);
if security && !is_release_tag(r) {
return Err(MnemoError::Invalid(format!(
"a SECURITY finding is verified against a published release tag (v1.2.3), \
not {r:?}"
)));
}
self.finding_move(id, finding_status::VERIFIED, r, |m, by| {
m.metadata
.insert(MNEMO_META_VERIFIED_REF.into(), Value::String(r.to_string()));
m.metadata
.insert(MNEMO_META_VERIFIED_BY.into(), Value::String(by.to_string()));
if security {
m.metadata.insert(
crate::memory::MNEMO_META_VISIBILITY.into(),
Value::String("team".into()),
);
}
})
}
fn finding_move(
&mut self,
id: &str,
to: &str,
note: &str,
set: impl FnOnce(&mut Memory, &str),
) -> Result<Finding> {
if self.read_only {
return Err(MnemoError::ReadOnly);
}
let Some(mut m) = self.finding_record(id)? else {
return Err(MnemoError::Invalid(format!("no finding {id:?}")));
};
let f = Finding::from_memory(&m).expect("a finding");
if !FINDING_TRANSITIONS.contains(&(f.status.as_str(), to)) {
return Err(MnemoError::Invalid(format!(
"a finding can't go from {} to {to}",
f.status
)));
}
let by = self.author.clone().unwrap_or_else(|| "anonymous".into());
let now = self.coordination_now();
m.metadata
.insert(MNEMO_META_STATUS.into(), Value::String(to.to_string()));
set(&mut m, &by);
Self::task_history(&mut m, &f.status, to, &by, now, &[("note", note)]);
let rid = m.id;
self.put(m)?;
Ok(Finding::from_memory(&self.get(&rid)?).expect("a finding"))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn finding_ids() {
for ok in ["RB-014.1", "R-011.2", "REV-1.10", "A-0.0"] {
assert!(valid_finding_id(ok), "{ok}");
}
for bad in [
"",
"rb-014.1",
"RB014.1",
"RB-014",
"RB-014.",
"RB-.1",
"RB-01a.1",
"RB-014.1.2",
"R B-1.1",
"RB-1.1 ",
"-1.1",
] {
assert!(!valid_finding_id(bad), "{bad}");
}
assert_eq!(batch_of("RB-014.12"), "RB-014");
assert!(parse_id("RB-9.1") < parse_id("RB-10.1"));
assert_eq!(parse_id("RB-0900.1"), parse_id("RB-900.1"));
}
#[test]
fn release_tags() {
for ok in ["v0.18.0", "v1.2.3", "v10.20.30"] {
assert!(is_release_tag(ok), "{ok}");
}
for bad in [
"",
"0.18.0",
"v0.18",
"v0.18.0-rc1",
"v0.18.0.1",
"abc1234",
"v.1.2",
"V1.2.3",
"v1..3",
] {
assert!(!is_release_tag(bad), "{bad}");
}
}
}