Bendik LynghaugandClaude Opus 5
44c7ee6870
iOS is the one client none of the mail autoconfiguration reaches: Apple Mail reads neither Mozilla autoconfig nor Autodiscover for IMAP, so adding an account means the device probing for ports - and a probe that meets a filtered port waits out a TCP timeout and reports the account as unverifiable, which the person reads as a wrong password. A profile states the hosts and the ports instead, and carries mail, calendars and contacts in one install. It invents none of them: site.yaml names a PACC document - the standard defined to be fetched from the mail domain itself - and every host, port and collection path comes from there, so the server is described in one place and the profile follows it. The document holds no address, username or password. iOS asks for those at install, which means one profile serves everyone with an account and it can be fetched by anyone: it says no more than PACC already says in public. Identifiers are derived from the site and the payload rather than drawn at random, because iOS replaces a profile whose ids it knows and stacks a duplicate when they differ. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_015GeH3y8fwTaTudaD88P57o
1741 lines
70 KiB
Rust
1741 lines
70 KiB
Rust
//! A business's needs, stated apart from how its pages word them.
|
|
//!
|
|
//! A content repo may ship a `needs.yaml` at its root: each *need* says
|
|
//! who wants what, where they enter, which bucket the answer must land
|
|
//! in, and which group has to be able to carry it to a finished state.
|
|
//! Two things are checked against it:
|
|
//!
|
|
//! - **Structure** (`check`): deterministic. A path of submissions
|
|
//! leads from the entry page to the bucket, within an effort budget;
|
|
//! the handling group has a desk over that bucket; every finished
|
|
//! state is reachable through the moves that desk offers, and no
|
|
//! record strands on the way.
|
|
//! - **Wording** (`tasks` / `score`): each *persona* is a visitor in
|
|
//! their own words. Every page on their path becomes one typed
|
|
//! `choice` question for an external answering engine - the page's
|
|
//! question, its alternatives as the options - and the engine's picks
|
|
//! are scored against the alternatives that actually meet the need.
|
|
//! A misroute is a wording defect: the page said one thing and the
|
|
//! visitor heard another.
|
|
//!
|
|
//! The engine is deliberately outside this crate: tasks go out as
|
|
//! JSONL, answers come back as JSONL, so any classifier or LLM can sit
|
|
//! in between and be compared on the same tasks.
|
|
|
|
use std::collections::{BTreeMap, HashMap, HashSet, VecDeque};
|
|
|
|
use serde::{Deserialize, Serialize};
|
|
|
|
use crate::aggregates::AggregateSchema;
|
|
use crate::content::{action_target_id, Alternative, Question};
|
|
|
|
#[derive(Debug, Default, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct NeedsFile {
|
|
#[serde(default)]
|
|
pub needs: Vec<Need>,
|
|
#[serde(default)]
|
|
pub personas: Vec<Persona>,
|
|
/// The tones of voice the site is told in, one storyline each
|
|
/// (portal docs, Storylines). Named here so the report can say
|
|
/// which tone a storyline index is; the checks read the first.
|
|
#[serde(default)]
|
|
pub tones: Vec<String>,
|
|
}
|
|
|
|
#[derive(Debug, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct Need {
|
|
pub id: String,
|
|
/// The kind of visitor - prose, for the reader of the report.
|
|
pub who: String,
|
|
pub wants: String,
|
|
/// The page they arrive on.
|
|
#[serde(default = "root")]
|
|
pub enters: String,
|
|
/// The group they hold when they arrive; unset means anonymous.
|
|
#[serde(default)]
|
|
pub enters_as: Option<String>,
|
|
/// The alternative on the entry page that serves this need, when
|
|
/// several record into the same bucket.
|
|
#[serde(default)]
|
|
pub via: Option<String>,
|
|
/// The bucket their answer must be recorded into.
|
|
pub lands_in: String,
|
|
/// The group that must be able to see the record and move it.
|
|
pub handled_by: String,
|
|
/// The states that count as handled.
|
|
pub done_when: Vec<String>,
|
|
/// Submissions the visitor may be asked for before the record
|
|
/// exists.
|
|
#[serde(default = "default_max_steps")]
|
|
pub max_steps: usize,
|
|
/// Required fields across the whole path - the onboarding effort
|
|
/// budget.
|
|
#[serde(default)]
|
|
pub max_fields: Option<usize>,
|
|
/// Declared, and knowingly not open yet: what is missing reports
|
|
/// as a warning, so the gap stays visible without failing CI.
|
|
#[serde(default)]
|
|
pub planned: bool,
|
|
/// Open before and closed for now (full up, out of season): its
|
|
/// card is on the page with no form. Reports like `planned`.
|
|
#[serde(default)]
|
|
pub paused: bool,
|
|
/// Each state of the bucket in plain words, in the site's
|
|
/// language, for the scorer: state ids are ASCII, and a Norwegian
|
|
/// `ikke_lost` reads as English to a model.
|
|
#[serde(default)]
|
|
pub stage_words: std::collections::BTreeMap<String, String>,
|
|
/// The finished states that are a good outcome for the business -
|
|
/// a subset of `done_when`. "lost" is finished; "won" is success.
|
|
/// What a simulation or a live bucket report counts toward.
|
|
#[serde(default)]
|
|
pub success: Vec<String>,
|
|
/// Every stage the business said a case goes through, in its own
|
|
/// order, first to last. Written from how the business describes
|
|
/// its work, before any state machine exists, so that a machine
|
|
/// which quietly skips a stage ("we go and look, then we quote"
|
|
/// becoming open -> quoted) fails instead of passing.
|
|
#[serde(default)]
|
|
pub stages: Vec<String>,
|
|
/// Other groups whose desks carry some of this need's moves: a
|
|
/// site manager closing what a project manager opened. Their
|
|
/// buttons count toward reaching `done_when` exactly as
|
|
/// `handled_by`'s do. `handled_by` must still hold a desk of its
|
|
/// own - someone has to be answerable for the record.
|
|
#[serde(default)]
|
|
pub also_moved_by: Vec<String>,
|
|
}
|
|
|
|
fn root() -> String {
|
|
"/".to_string()
|
|
}
|
|
|
|
fn default_max_steps() -> usize {
|
|
2
|
|
}
|
|
|
|
#[derive(Debug, Deserialize)]
|
|
#[serde(deny_unknown_fields)]
|
|
pub struct Persona {
|
|
pub id: String,
|
|
pub need: String,
|
|
/// The visitor's situation in their own words - never the page's.
|
|
pub text: String,
|
|
}
|
|
|
|
pub fn parse(raw: &str) -> anyhow::Result<NeedsFile> {
|
|
serde_yaml::from_str(raw).map_err(|e| anyhow::anyhow!("parsing needs.yaml: {e}"))
|
|
}
|
|
|
|
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
|
|
pub enum Level {
|
|
Fail,
|
|
Warn,
|
|
}
|
|
|
|
#[derive(Debug)]
|
|
pub struct Finding {
|
|
/// The need's id, or the bucket's name when `scope` is "bucket".
|
|
pub need: String,
|
|
pub level: Level,
|
|
pub message: String,
|
|
/// "need" for a need's own path; "bucket" for what holds for every
|
|
/// record in a bucket whichever need brought it in.
|
|
pub scope: &'static str,
|
|
/// What kind of gap it is, stable across releases: `strand`,
|
|
/// `edge-unoffered`, `done-unreachable`, ... (docs/lint.md).
|
|
pub code: &'static str,
|
|
/// What in the content it is about: a state, a move (`from>to`), a
|
|
/// page. With the scope, need and code it makes the finding's id.
|
|
pub subject: String,
|
|
}
|
|
|
|
impl Finding {
|
|
/// The same gap keeps the same id however its message is worded,
|
|
/// so a fix round can tell what it closed, what is still open and
|
|
/// what it broke. FNV-1a over scope, need, code and subject.
|
|
pub fn id(&self) -> String {
|
|
let mut hash: u64 = 0xcbf2_9ce4_8422_2325;
|
|
for part in [self.scope, &self.need, self.code, &self.subject] {
|
|
for byte in part.bytes().chain(std::iter::once(0)) {
|
|
hash ^= u64::from(byte);
|
|
hash = hash.wrapping_mul(0x0100_0000_01b3);
|
|
}
|
|
}
|
|
format!("{:08x}", hash >> 32)
|
|
}
|
|
|
|
/// The change that closes it, when the lint knows one: what follows
|
|
/// "fix:" in the message.
|
|
pub fn fix(&self) -> Option<&str> {
|
|
self.message.split_once(" - fix: ").map(|(_, fix)| fix)
|
|
}
|
|
|
|
/// One line of `--findings` JSONL.
|
|
pub fn to_json(&self) -> serde_json::Value {
|
|
serde_json::json!({
|
|
"id": self.id(),
|
|
"level": match self.level { Level::Fail => "fail", Level::Warn => "warn" },
|
|
"code": self.code,
|
|
"scope": self.scope,
|
|
"need": self.need,
|
|
"subject": self.subject,
|
|
"message": self.message,
|
|
"fix": self.fix(),
|
|
})
|
|
}
|
|
}
|
|
|
|
#[derive(Clone, Debug, PartialEq, Eq)]
|
|
pub struct Step {
|
|
pub page: String,
|
|
pub alternative: String,
|
|
}
|
|
|
|
/// One alternative on a page that still meets the need, with the
|
|
/// cheapest way on from it.
|
|
struct Viable {
|
|
alternative: String,
|
|
path: Vec<Step>,
|
|
fields: usize,
|
|
records_with_action: Option<bool>,
|
|
}
|
|
|
|
type Questions = HashMap<String, Question>;
|
|
|
|
fn visible(q: &Question, as_group: Option<&str>) -> bool {
|
|
match &q.qualifies {
|
|
None => true,
|
|
Some(group) => as_group == Some(group.as_str()),
|
|
}
|
|
}
|
|
|
|
/// What a person has to fill in: required fields, less the ones that
|
|
/// carry rather than ask - a `record` naming the case an answer is
|
|
/// about, a `hidden` preset - which cost nobody anything.
|
|
fn required_fields(alt: &Alternative) -> usize {
|
|
alt.features
|
|
.iter()
|
|
.flat_map(|f| &f.requirements)
|
|
.filter(|r| !r.optional && r.kind != "record" && r.kind != "hidden")
|
|
.count()
|
|
}
|
|
|
|
/// The alternatives on `page` from which the need is still met within
|
|
/// `remaining` submissions.
|
|
fn viable(
|
|
questions: &Questions,
|
|
need: &Need,
|
|
page: &Question,
|
|
remaining: usize,
|
|
entry: bool,
|
|
include_disabled: bool,
|
|
trail: &mut Vec<String>,
|
|
) -> Vec<Viable> {
|
|
let mut out = Vec::new();
|
|
if remaining == 0 {
|
|
return out;
|
|
}
|
|
for alt in page
|
|
.alternatives
|
|
.iter()
|
|
.filter(|a| include_disabled || !a.disabled)
|
|
{
|
|
if entry && need.via.as_deref().is_some_and(|via| via != alt.name) {
|
|
continue;
|
|
}
|
|
let step = Step {
|
|
page: page.id.clone(),
|
|
alternative: alt.name.clone(),
|
|
};
|
|
let fields = required_fields(alt);
|
|
if alt.record_as.as_deref() == Some(need.lands_in.as_str()) {
|
|
out.push(Viable {
|
|
alternative: alt.name.clone(),
|
|
path: vec![step],
|
|
fields,
|
|
records_with_action: Some(alt.action.is_some()),
|
|
});
|
|
continue;
|
|
}
|
|
let Some(target) = alt
|
|
.action
|
|
.as_deref()
|
|
.and_then(|a| action_target_id(questions, a))
|
|
.and_then(|id| questions.get(&id))
|
|
else {
|
|
continue;
|
|
};
|
|
if trail.contains(&target.id) || !visible(target, need.enters_as.as_deref()) {
|
|
continue;
|
|
}
|
|
trail.push(target.id.clone());
|
|
let onward = viable(
|
|
questions,
|
|
need,
|
|
target,
|
|
remaining - 1,
|
|
false,
|
|
include_disabled,
|
|
trail,
|
|
);
|
|
trail.pop();
|
|
if let Some(best) = onward.into_iter().min_by_key(|v| (v.path.len(), v.fields)) {
|
|
let mut path = vec![step];
|
|
path.extend(best.path);
|
|
out.push(Viable {
|
|
alternative: alt.name.clone(),
|
|
path,
|
|
fields: fields + best.fields,
|
|
records_with_action: best.records_with_action,
|
|
});
|
|
}
|
|
}
|
|
out
|
|
}
|
|
|
|
fn entry_viable(questions: &Questions, need: &Need, include_disabled: bool) -> Option<Vec<Viable>> {
|
|
let page = questions.get(&need.enters)?;
|
|
let mut trail = vec![page.id.clone()];
|
|
Some(viable(
|
|
questions,
|
|
need,
|
|
page,
|
|
need.max_steps,
|
|
true,
|
|
include_disabled,
|
|
&mut trail,
|
|
))
|
|
}
|
|
|
|
/// The cheapest path that meets the need, if any.
|
|
pub fn path_for(questions: &Questions, need: &Need) -> Option<Vec<Step>> {
|
|
entry_viable(questions, need, false)?
|
|
.into_iter()
|
|
.min_by_key(|v| (v.path.len(), v.fields))
|
|
.map(|v| v.path)
|
|
}
|
|
|
|
struct Desk {
|
|
page: String,
|
|
group: Option<String>,
|
|
/// The page's own `qualifies`, kept apart from the resource's
|
|
/// `requires_group`: when both are set and differ, only members of
|
|
/// both ever see the buttons.
|
|
page_group: Option<String>,
|
|
/// (from, to, button label)
|
|
moves: Vec<(String, String, String)>,
|
|
}
|
|
|
|
fn desks_over(questions: &Questions, bucket: &str) -> Vec<Desk> {
|
|
let mut desks = Vec::new();
|
|
for q in questions.values() {
|
|
for resource in q
|
|
.alternatives
|
|
.iter()
|
|
.flat_map(|a| &a.features)
|
|
.filter_map(|f| f.resource.as_ref())
|
|
.filter(|r| r.bucket() == Some(bucket))
|
|
{
|
|
desks.push(Desk {
|
|
page: q.id.clone(),
|
|
group: resource
|
|
.requires_group
|
|
.clone()
|
|
.or_else(|| q.qualifies.clone()),
|
|
page_group: q.qualifies.clone(),
|
|
moves: resource
|
|
.transitions
|
|
.iter()
|
|
.map(|t| (t.from.clone(), t.to.clone(), t.label.clone()))
|
|
.collect(),
|
|
});
|
|
}
|
|
}
|
|
desks.sort_by(|a, b| a.page.cmp(&b.page));
|
|
desks
|
|
}
|
|
|
|
/// Self-service moves in `bucket` - a visitor holding their own
|
|
/// record's link, no group involved (unsubscribe, withdraw) - as
|
|
/// (from, to), from the states each may be made from.
|
|
fn self_moves(questions: &Questions, bucket: &str, initial: &str) -> Vec<(String, String)> {
|
|
questions
|
|
.values()
|
|
.flat_map(|q| &q.alternatives)
|
|
.filter_map(|a| a.self_transition.as_ref())
|
|
.filter(|s| s.bucket == bucket)
|
|
.flat_map(|s| {
|
|
s.from_states(initial)
|
|
.into_iter()
|
|
.map(|from| (from, s.to.clone()))
|
|
})
|
|
.collect()
|
|
}
|
|
|
|
/// The moves a clock makes in `schema` (`after:` on a state), as
|
|
/// (from, to). Nobody presses them, and they still move records.
|
|
fn clock_moves(schema: &AggregateSchema) -> Vec<(String, String)> {
|
|
let mut moves: Vec<(String, String)> = schema
|
|
.after_for_state
|
|
.iter()
|
|
.map(|(from, after)| (from.clone(), after.to.clone()))
|
|
.collect();
|
|
moves.sort();
|
|
moves
|
|
}
|
|
|
|
/// States reachable from `start` along `moves`.
|
|
fn reachable(start: &str, moves: &[(String, String)]) -> HashSet<String> {
|
|
let mut reached = HashSet::from([start.to_string()]);
|
|
let mut queue = VecDeque::from([start.to_string()]);
|
|
while let Some(state) = queue.pop_front() {
|
|
for (_, to) in moves.iter().filter(|(from, _)| *from == state) {
|
|
if reached.insert(to.clone()) {
|
|
queue.push_back(to.clone());
|
|
}
|
|
}
|
|
}
|
|
reached
|
|
}
|
|
|
|
/// Who else offers `from -> to` in the bucket, as "page (group)", for
|
|
/// a finding that has to say where the missing button already is.
|
|
fn offered_elsewhere(desks: &[Desk], from: &str, to: &str) -> Vec<String> {
|
|
desks
|
|
.iter()
|
|
.filter(|d| d.moves.iter().any(|(f, t, _)| f == from && t == to))
|
|
.map(|d| format!("{} ({})", d.page, d.group.as_deref().unwrap_or("ungated")))
|
|
.collect()
|
|
}
|
|
|
|
/// Structural check of every need. `Fail` findings mean the business
|
|
/// need is not met by the content as written.
|
|
pub fn check(
|
|
file: &NeedsFile,
|
|
questions: &Questions,
|
|
aggregates: &HashMap<String, AggregateSchema>,
|
|
) -> Vec<Finding> {
|
|
let mut findings = Vec::new();
|
|
let mut seen = HashSet::new();
|
|
// (bucket, state) a need already reported - stranding on its way
|
|
// to done, or out of its reach - so the bucket pass does not say
|
|
// it twice.
|
|
let mut strands_reported: HashSet<(String, String)> = HashSet::new();
|
|
let mut unreached_reported: HashSet<(String, String)> = HashSet::new();
|
|
for need in &file.needs {
|
|
let mut report = |level: Level, code: &'static str, subject: String, message: String| {
|
|
findings.push(Finding {
|
|
need: need.id.clone(),
|
|
scope: "need",
|
|
code,
|
|
subject,
|
|
level: if need.planned || need.paused {
|
|
Level::Warn
|
|
} else {
|
|
level
|
|
},
|
|
message: match (need.paused, need.planned, level == Level::Fail) {
|
|
(true, _, true) => format!("paused, not open now: {message}"),
|
|
(false, true, true) => format!("planned, not met yet: {message}"),
|
|
_ => message,
|
|
},
|
|
})
|
|
};
|
|
if !seen.insert(need.id.as_str()) {
|
|
report(
|
|
Level::Fail,
|
|
"need-duplicate",
|
|
String::new(),
|
|
"declared more than once".to_string(),
|
|
);
|
|
continue;
|
|
}
|
|
|
|
// The visitor's side: can they get their answer recorded?
|
|
match questions.get(&need.enters) {
|
|
None => report(
|
|
Level::Fail,
|
|
"entry-missing",
|
|
need.enters.clone(),
|
|
format!("entry page {:?} does not exist", need.enters),
|
|
),
|
|
Some(page) if !visible(page, need.enters_as.as_deref()) => report(
|
|
Level::Fail,
|
|
"entry-gated",
|
|
need.enters.clone(),
|
|
format!(
|
|
"entry page {:?} is gated on {:?}, which this visitor does not hold",
|
|
need.enters, page.qualifies
|
|
),
|
|
),
|
|
Some(page) => {
|
|
if page.responsible.is_none() {
|
|
report(
|
|
Level::Warn,
|
|
"entry-no-responsible",
|
|
need.enters.clone(),
|
|
format!(
|
|
"entry page {:?} names no one responsible to turn to",
|
|
need.enters
|
|
),
|
|
);
|
|
}
|
|
let best = entry_viable(questions, need, false)
|
|
.unwrap_or_default()
|
|
.into_iter()
|
|
.min_by_key(|v| (v.path.len(), v.fields));
|
|
match best {
|
|
None if entry_viable(questions, need, true).is_some_and(|v| !v.is_empty()) => {
|
|
let blocked = entry_viable(questions, need, true)
|
|
.unwrap_or_default()
|
|
.into_iter()
|
|
.min_by_key(|v| (v.path.len(), v.fields))
|
|
.map(|v| v.path)
|
|
.unwrap_or_default();
|
|
let at = blocked
|
|
.iter()
|
|
.find(|s| {
|
|
questions[&s.page]
|
|
.alternatives
|
|
.iter()
|
|
.any(|a| a.name == s.alternative && a.disabled)
|
|
})
|
|
.map(|s| format!("{:?} on {}", s.alternative, s.page))
|
|
.unwrap_or_default();
|
|
report(
|
|
Level::Fail,
|
|
"path-closed",
|
|
at.clone(),
|
|
format!(
|
|
"the path exists but is closed: {at} is `disabled`, so the answer is advertised and refused"
|
|
),
|
|
)
|
|
}
|
|
None => report(
|
|
Level::Fail,
|
|
"path-missing",
|
|
String::new(),
|
|
format!(
|
|
"no path from {:?}{} records into {:?} within {} submission(s)",
|
|
need.enters,
|
|
need.via
|
|
.as_ref()
|
|
.map(|v| format!(" via {v:?}"))
|
|
.unwrap_or_default(),
|
|
need.lands_in,
|
|
need.max_steps
|
|
),
|
|
),
|
|
Some(best) => {
|
|
if let Some(budget) = need.max_fields {
|
|
if best.fields > budget {
|
|
report(
|
|
Level::Fail,
|
|
"path-over-budget",
|
|
String::new(),
|
|
format!(
|
|
"the path asks for {} required field(s), over the budget of {budget}",
|
|
best.fields
|
|
),
|
|
);
|
|
}
|
|
}
|
|
if best.records_with_action == Some(false) {
|
|
report(
|
|
Level::Warn,
|
|
"path-no-action",
|
|
String::new(),
|
|
"the recording alternative has no `action` - the visitor is never told what happens next".to_string(),
|
|
);
|
|
}
|
|
}
|
|
}
|
|
}
|
|
}
|
|
|
|
// The business's side: can the handling group finish it?
|
|
let Some(schema) = aggregates.get(&need.lands_in) else {
|
|
report(
|
|
Level::Fail,
|
|
"machine-missing",
|
|
need.lands_in.clone(),
|
|
format!(
|
|
"aggregates.yaml declares no state machine for {:?}",
|
|
need.lands_in
|
|
),
|
|
);
|
|
continue;
|
|
};
|
|
let desks = desks_over(questions, &need.lands_in);
|
|
let own: Vec<&Desk> = desks
|
|
.iter()
|
|
.filter(|d| {
|
|
d.group.as_deref().is_some_and(|g| {
|
|
g == need.handled_by || need.also_moved_by.iter().any(|m| m == g)
|
|
})
|
|
})
|
|
.collect();
|
|
if !desks
|
|
.iter()
|
|
.any(|d| d.group.as_deref() == Some(need.handled_by.as_str()))
|
|
{
|
|
let others: Vec<String> = desks
|
|
.iter()
|
|
.map(|d| format!("{} ({})", d.page, d.group.as_deref().unwrap_or("ungated")))
|
|
.collect();
|
|
report(
|
|
Level::Fail,
|
|
"desk-missing",
|
|
need.handled_by.clone(),
|
|
format!(
|
|
"no desk gated on {:?} reads {:?}{}",
|
|
need.handled_by,
|
|
need.lands_in,
|
|
if others.is_empty() {
|
|
String::new()
|
|
} else {
|
|
format!(" - it is read by {}", others.join(", "))
|
|
}
|
|
),
|
|
);
|
|
continue;
|
|
}
|
|
// Every move that carries this need's records: the buttons on
|
|
// the desks of handled_by/also_moved_by, the visitor's own
|
|
// links, and the clocks.
|
|
let mut moves: Vec<(String, String)> = own
|
|
.iter()
|
|
.flat_map(|d| &d.moves)
|
|
.filter(|(from, to, _)| schema.allowed(from).contains(to))
|
|
.map(|(from, to, _)| (from.clone(), to.clone()))
|
|
.collect();
|
|
moves.extend(self_moves(questions, &need.lands_in, &schema.initial));
|
|
moves.extend(clock_moves(schema));
|
|
let exits = |state: &str| -> Vec<String> {
|
|
moves
|
|
.iter()
|
|
.filter(|(from, _)| from == state)
|
|
.map(|(_, to)| to.clone())
|
|
.collect()
|
|
};
|
|
let movers = std::iter::once(need.handled_by.as_str())
|
|
.chain(need.also_moved_by.iter().map(String::as_str))
|
|
.map(|g| format!("{g:?}"))
|
|
.collect::<Vec<_>>()
|
|
.join(" or ");
|
|
// The fix for a missing move: the button on handled_by's desk,
|
|
// or the group whose desk already has it added to also_moved_by.
|
|
let fix_for = |from: &str, to: &str| -> String {
|
|
let elsewhere = offered_elsewhere(&desks, from, to);
|
|
let desk = own.first().map(|d| d.page.as_str()).unwrap_or("their desk");
|
|
if elsewhere.is_empty() {
|
|
format!(
|
|
"add `{{ from: {from}, to: {to}, label: ... }}` to the transitions on {desk}"
|
|
)
|
|
} else {
|
|
format!(
|
|
"{} already offers it - add that group to also_moved_by, or add `{{ from: {from}, to: {to}, label: ... }}` on {desk}",
|
|
elsewhere.join(", ")
|
|
)
|
|
}
|
|
};
|
|
let done: HashSet<&str> = need.done_when.iter().map(String::as_str).collect();
|
|
// Reachability walks the whole machine (a finished state may
|
|
// lead on to another: subscribed, then unsubscribed). Stranding
|
|
// only counts on the way to the first finished state here; what
|
|
// strands a record afterwards is the bucket's finding (below).
|
|
let mut reached: HashSet<String> = HashSet::from([schema.initial.clone()]);
|
|
let mut queue = VecDeque::from([(schema.initial.clone(), false)]);
|
|
let mut stranded = Vec::new();
|
|
while let Some((state, past_done)) = queue.pop_front() {
|
|
let past_done = past_done || done.contains(state.as_str());
|
|
let next = exits(&state);
|
|
if next.is_empty() && !past_done {
|
|
stranded.push(state.clone());
|
|
}
|
|
for to in next {
|
|
if reached.insert(to.clone()) {
|
|
queue.push_back((to, past_done));
|
|
}
|
|
}
|
|
}
|
|
// The declared edges into `state` from somewhere a record does
|
|
// get to: the moves that would close the gap.
|
|
let ways_in = |state: &str| -> Vec<(String, String)> {
|
|
let mut ways: Vec<(String, String)> = reached
|
|
.iter()
|
|
.filter(|from| schema.allowed(from).iter().any(|to| to == state))
|
|
.map(|from| (from.clone(), state.to_string()))
|
|
.collect();
|
|
ways.sort();
|
|
ways
|
|
};
|
|
let missing = |state: &str| -> String {
|
|
match ways_in(state).first() {
|
|
Some((from, to)) => format!(" - fix: {}", fix_for(from, to)),
|
|
None => format!(
|
|
" - fix: no state a record reaches has a declared edge into it; add one in aggregates.yaml under {:?}",
|
|
need.lands_in
|
|
),
|
|
}
|
|
};
|
|
for state in &need.done_when {
|
|
if !schema.has_state(state) {
|
|
report(
|
|
Level::Fail,
|
|
"done-unknown",
|
|
state.clone(),
|
|
format!(
|
|
"done_when names {state:?}, which {:?} has no such state",
|
|
need.lands_in
|
|
),
|
|
);
|
|
} else if !reached.contains(state) {
|
|
unreached_reported.insert((need.lands_in.clone(), state.clone()));
|
|
report(
|
|
Level::Fail,
|
|
"done-unreachable",
|
|
state.clone(),
|
|
format!(
|
|
"{:?} cannot move a record to {state:?} - no desk of theirs offers the moves{}",
|
|
need.handled_by,
|
|
missing(state)
|
|
),
|
|
);
|
|
}
|
|
}
|
|
for stage in &need.stages {
|
|
if !schema.has_state(stage) {
|
|
report(
|
|
Level::Fail,
|
|
"stage-unknown",
|
|
stage.clone(),
|
|
format!(
|
|
"the business describes a stage {stage:?} that {:?} has no state for",
|
|
need.lands_in
|
|
),
|
|
);
|
|
} else if !reached.contains(stage) {
|
|
unreached_reported.insert((need.lands_in.clone(), stage.clone()));
|
|
report(
|
|
Level::Fail,
|
|
"stage-unreachable",
|
|
stage.clone(),
|
|
format!(
|
|
"stage {stage:?} exists but {:?} is offered no moves that reach it{}",
|
|
need.handled_by,
|
|
missing(stage)
|
|
),
|
|
);
|
|
}
|
|
}
|
|
// In the business's order: each working stage reachable from
|
|
// the one before it, so a machine where "quoted" cannot follow
|
|
// "surveyed" does not pass for one that goes surveyed -> quoted.
|
|
// The finished states that close the list are alternatives
|
|
// (won, lost), not a sequence, so they are left out.
|
|
for pair in need.stages.windows(2) {
|
|
let (before, after) = (&pair[0], &pair[1]);
|
|
if done.contains(before.as_str()) || done.contains(after.as_str()) {
|
|
continue;
|
|
}
|
|
if reached.contains(before)
|
|
&& reached.contains(after)
|
|
&& !reachable(before, &moves).contains(after)
|
|
{
|
|
report(
|
|
Level::Fail,
|
|
"stage-order",
|
|
format!("{before}>{after}"),
|
|
format!(
|
|
"stage {after:?} comes after {before:?} for the business, but no move leads on from {before:?} to it{}",
|
|
match schema.allowed(before).iter().find(|to| reachable(to, &moves).contains(after) || *to == after) {
|
|
Some(to) => format!(" - fix: {}", fix_for(before, to)),
|
|
None => format!(" - fix: add an edge from {before:?} toward {after:?} in aggregates.yaml under {:?}", need.lands_in),
|
|
}
|
|
),
|
|
);
|
|
}
|
|
}
|
|
for state in &need.success {
|
|
if !need.done_when.contains(state) {
|
|
report(
|
|
Level::Fail,
|
|
"success-not-done",
|
|
state.clone(),
|
|
format!("success names {state:?}, which is not one of done_when"),
|
|
);
|
|
}
|
|
}
|
|
stranded.sort();
|
|
for state in &stranded {
|
|
strands_reported.insert((need.lands_in.clone(), state.clone()));
|
|
}
|
|
for state in stranded {
|
|
let fix = match schema.allowed(&state).first() {
|
|
Some(to) => format!(" - fix: {}", fix_for(&state, to)),
|
|
None => format!(
|
|
" - fix: {:?} declares no way out of it; add {state:?} to done_when if it is finished, or an edge out in aggregates.yaml",
|
|
need.lands_in
|
|
),
|
|
};
|
|
report(
|
|
Level::Fail,
|
|
"strand",
|
|
state.clone(),
|
|
format!("records strand in {state:?}: {movers} is offered no move out of it{fix}"),
|
|
);
|
|
}
|
|
}
|
|
|
|
findings.extend(operations(
|
|
file,
|
|
questions,
|
|
aggregates,
|
|
&strands_reported,
|
|
&unreached_reported,
|
|
));
|
|
|
|
let need_ids: HashSet<&str> = file.needs.iter().map(|n| n.id.as_str()).collect();
|
|
for persona in &file.personas {
|
|
if !need_ids.contains(persona.need.as_str()) {
|
|
findings.push(Finding {
|
|
need: persona.need.clone(),
|
|
scope: "need",
|
|
code: "persona-unknown-need",
|
|
subject: persona.id.clone(),
|
|
level: Level::Fail,
|
|
message: format!(
|
|
"persona {:?} points at a need that is not declared",
|
|
persona.id
|
|
),
|
|
});
|
|
}
|
|
}
|
|
findings
|
|
}
|
|
|
|
/// What must hold for every record in a bucket some need lands in,
|
|
/// whichever need brought it: every state is somewhere a record can
|
|
/// get to, no state a record gets to holds it with no way on (before
|
|
/// done or after), every declared move is a button someone has, every
|
|
/// desk can be seen by whoever its buttons are for, and every mail
|
|
/// goes out from a state records reach, saying only what the record
|
|
/// holds.
|
|
fn operations(
|
|
file: &NeedsFile,
|
|
questions: &Questions,
|
|
aggregates: &HashMap<String, AggregateSchema>,
|
|
strands_reported: &HashSet<(String, String)>,
|
|
unreached_reported: &HashSet<(String, String)>,
|
|
) -> Vec<Finding> {
|
|
let mut findings = Vec::new();
|
|
let mut buckets: Vec<&str> = file.needs.iter().map(|n| n.lands_in.as_str()).collect();
|
|
buckets.sort();
|
|
buckets.dedup();
|
|
for bucket in buckets {
|
|
let Some(schema) = aggregates.get(bucket) else {
|
|
continue;
|
|
};
|
|
let needs: Vec<&Need> = file.needs.iter().filter(|n| n.lands_in == bucket).collect();
|
|
// Only open needs make a gap fail; a bucket that only planned
|
|
// or paused needs use reports it as a warning.
|
|
let open = needs.iter().any(|n| !n.planned && !n.paused);
|
|
let mut report = |level: Level, code: &'static str, subject: String, message: String| {
|
|
findings.push(Finding {
|
|
need: bucket.to_string(),
|
|
scope: "bucket",
|
|
code,
|
|
subject,
|
|
level: if open { level } else { Level::Warn },
|
|
message,
|
|
})
|
|
};
|
|
let desks = desks_over(questions, bucket);
|
|
let mut moves: Vec<(String, String)> = desks
|
|
.iter()
|
|
.flat_map(|d| &d.moves)
|
|
.filter(|(from, to, _)| schema.allowed(from).contains(to))
|
|
.map(|(from, to, _)| (from.clone(), to.clone()))
|
|
.collect();
|
|
moves.extend(self_moves(questions, bucket, &schema.initial));
|
|
moves.extend(clock_moves(schema));
|
|
let reached = reachable(&schema.initial, &moves);
|
|
let offered = |from: &str, to: &str| moves.iter().any(|(f, t)| f == from && t == to);
|
|
// Where a missing button goes: the desk of the group answerable
|
|
// for the bucket's first need.
|
|
let home = needs
|
|
.iter()
|
|
.find_map(|n| {
|
|
desks
|
|
.iter()
|
|
.find(|d| d.group.as_deref() == Some(n.handled_by.as_str()))
|
|
})
|
|
.map(|d| d.page.clone())
|
|
.unwrap_or_else(|| "the handling group's desk".to_string());
|
|
let button = |from: &str, to: &str| {
|
|
format!("add `{{ from: {from}, to: {to}, label: ... }}` to the transitions on {home}")
|
|
};
|
|
|
|
let mut states: Vec<&String> = schema.event_for_state.keys().collect();
|
|
states.sort();
|
|
for state in &states {
|
|
if reached.contains(*state)
|
|
|| unreached_reported.contains(&(bucket.to_string(), (*state).clone()))
|
|
{
|
|
continue;
|
|
}
|
|
let mut ways: Vec<&String> = reached
|
|
.iter()
|
|
.filter(|from| schema.allowed(from).contains(state))
|
|
.collect();
|
|
ways.sort();
|
|
report(
|
|
Level::Fail,
|
|
"state-unreached",
|
|
(*state).clone(),
|
|
format!(
|
|
"state {state:?} is never reached: no desk, link or clock moves a record there - fix: {}",
|
|
match ways.first() {
|
|
Some(from) => button(from, state),
|
|
None => "declare an edge into it from a state records reach in aggregates.yaml, or remove it".to_string(),
|
|
}
|
|
),
|
|
);
|
|
}
|
|
for state in states.iter().filter(|s| reached.contains(**s)) {
|
|
let out = schema.allowed(state);
|
|
if out.is_empty() {
|
|
continue; // a final state: nothing should move it
|
|
}
|
|
let offered_out: Vec<&String> = out.iter().filter(|to| offered(state, to)).collect();
|
|
if offered_out.is_empty() {
|
|
if !strands_reported.contains(&(bucket.to_string(), (*state).clone())) {
|
|
report(
|
|
Level::Fail,
|
|
"strand",
|
|
(*state).clone(),
|
|
format!(
|
|
"records strand in {state:?}: {bucket:?} declares moves on to {} but no desk, link or clock offers one - fix: {}",
|
|
out.join(", "),
|
|
button(state, &out[0])
|
|
),
|
|
);
|
|
}
|
|
continue;
|
|
}
|
|
for to in out.iter().filter(|to| !offered(state, to)) {
|
|
report(
|
|
Level::Warn,
|
|
"edge-unoffered",
|
|
format!("{state}>{to}"),
|
|
format!(
|
|
"the move {state:?} -> {to:?} is declared but no desk, link or clock offers it - fix: {}, or drop the edge from aggregates.yaml",
|
|
button(state, to)
|
|
),
|
|
);
|
|
}
|
|
}
|
|
for desk in &desks {
|
|
if let (Some(page_group), Some(group)) = (&desk.page_group, &desk.group) {
|
|
if page_group != group {
|
|
report(
|
|
Level::Warn,
|
|
"desk-gated-twice",
|
|
desk.page.clone(),
|
|
format!(
|
|
"the desk on {} is gated twice: the page qualifies {page_group:?}, its list requires {group:?}, so only members of both see the buttons - fix: make them the same group",
|
|
desk.page
|
|
),
|
|
);
|
|
}
|
|
}
|
|
}
|
|
// The fields a record of this bucket holds: everything asked on
|
|
// a form that records into it.
|
|
let fields: Vec<(&str, &str)> = questions
|
|
.values()
|
|
.flat_map(|q| &q.alternatives)
|
|
.filter(|a| a.record_as.as_deref() == Some(bucket))
|
|
.flat_map(|a| &a.features)
|
|
.flat_map(|f| &f.requirements)
|
|
.map(|r| (r.name.as_str(), r.kind.as_str()))
|
|
.collect();
|
|
let mut mail_states: Vec<(&String, &crate::aggregates::MailSpec)> =
|
|
schema.mail_for_state.iter().collect();
|
|
mail_states.sort_by(|a, b| a.0.cmp(b.0));
|
|
for (state, mail) in mail_states {
|
|
if !reached.contains(state) {
|
|
report(Level::Warn, "mail-unreachable", state.clone(), format!("the mail on entering {state:?} never goes out: no record reaches {state:?} - fix: make {state:?} reachable, or drop its mail"));
|
|
}
|
|
let mut unknown: Vec<String> = Vec::new();
|
|
for key in placeholders(&mail.subject)
|
|
.into_iter()
|
|
.chain(placeholders(&mail.body))
|
|
{
|
|
let known = match key.split_once('.') {
|
|
Some((parent, _)) => fields
|
|
.iter()
|
|
.any(|(name, kind)| *name == parent && *kind == "record"),
|
|
None => {
|
|
MAIL_BUILTINS.contains(&key.as_str())
|
|
|| fields.iter().any(|(name, _)| *name == key)
|
|
}
|
|
};
|
|
if !known && !unknown.contains(&key) {
|
|
unknown.push(key);
|
|
}
|
|
}
|
|
if !unknown.is_empty() {
|
|
let mut names: Vec<&str> = fields.iter().map(|(n, _)| *n).collect();
|
|
names.sort();
|
|
names.dedup();
|
|
report(
|
|
Level::Fail,
|
|
"mail-unknown-field",
|
|
state.clone(),
|
|
format!(
|
|
"the mail on entering {state:?} uses {}, which no form recording into {bucket:?} collects, so it would go out blank there - fix: use one of the fields the forms collect ({}), or ask for it on the form",
|
|
unknown.iter().map(|k| format!("{{{k}}}")).collect::<Vec<_>>().join(", "),
|
|
if names.is_empty() { "nothing".to_string() } else { names.join(", ") }
|
|
),
|
|
);
|
|
}
|
|
}
|
|
}
|
|
findings
|
|
}
|
|
|
|
/// What the mailer fills in on every state mail, whatever the record
|
|
/// holds (`mail::vars_for`, `mail::site_vars`, `mail::record_links`).
|
|
const MAIL_BUILTINS: &[&str] = &[
|
|
"site",
|
|
"site_name",
|
|
"chain",
|
|
"email",
|
|
"bucket",
|
|
"state",
|
|
"link",
|
|
"self_link",
|
|
"desk_link",
|
|
];
|
|
|
|
/// The `{key}`s in a mail template, read the way `mail::render` reads
|
|
/// them: letters, digits, `_`, `-` and `.`, closed by `}`.
|
|
fn placeholders(template: &str) -> Vec<String> {
|
|
let mut keys = Vec::new();
|
|
let mut rest = template;
|
|
while let Some(start) = rest.find('{') {
|
|
let after = &rest[start + 1..];
|
|
let len = after
|
|
.char_indices()
|
|
.take_while(|(_, c)| c.is_ascii_alphanumeric() || *c == '_' || *c == '-' || *c == '.')
|
|
.last()
|
|
.map(|(i, c)| i + c.len_utf8())
|
|
.unwrap_or(0);
|
|
if len > 0 && after[len..].starts_with('}') {
|
|
keys.push(after[..len].to_string());
|
|
}
|
|
rest = after;
|
|
}
|
|
keys
|
|
}
|
|
|
|
/// Everything a simulation of the business needs, resolved: each
|
|
/// need's path with the choice on every page and the form that gets
|
|
/// filled, each bucket's state machine with the buttons every desk
|
|
/// offers, and the personas. Portal resolves it because only portal
|
|
/// loads content the way the runtime does (derived ids, relative
|
|
/// refs, sections); whoever simulates reads plain JSON.
|
|
pub fn sim_model(
|
|
file: &NeedsFile,
|
|
questions: &Questions,
|
|
aggregates: &HashMap<String, AggregateSchema>,
|
|
) -> serde_json::Value {
|
|
use serde_json::json;
|
|
let mut needs = Vec::new();
|
|
let mut buckets = serde_json::Map::new();
|
|
for need in &file.needs {
|
|
let Some(path) = path_for(questions, need) else {
|
|
continue;
|
|
};
|
|
let steps: Vec<serde_json::Value> = path
|
|
.iter()
|
|
.enumerate()
|
|
.map(|(i, step)| {
|
|
let page = &questions[&step.page];
|
|
let mut trail: Vec<String> = path[..=i].iter().map(|s| s.page.clone()).collect();
|
|
let expect: Vec<String> =
|
|
viable(questions, need, page, need.max_steps - i, i == 0, false, &mut trail)
|
|
.into_iter()
|
|
.map(|v| v.alternative)
|
|
.collect();
|
|
let fields: Vec<serde_json::Value> = page
|
|
.alternatives
|
|
.iter()
|
|
.find(|a| a.name == step.alternative)
|
|
.into_iter()
|
|
.flat_map(|a| &a.features)
|
|
.flat_map(|f| &f.requirements)
|
|
.map(|r| {
|
|
json!({
|
|
"name": r.name,
|
|
"label": r.label.clone().unwrap_or_else(|| r.name.clone()),
|
|
"type": r.kind,
|
|
"optional": r.optional,
|
|
"options": r.options,
|
|
})
|
|
})
|
|
.collect();
|
|
json!({
|
|
"page": step.page,
|
|
"question": page.name,
|
|
"context": page_context(page),
|
|
"options": page.alternatives.iter().filter(|a| !a.disabled && leads_somewhere(a)).map(|a| json!({
|
|
"name": a.name,
|
|
"description": plain(&a.description),
|
|
})).collect::<Vec<_>>(),
|
|
"expect": expect,
|
|
"alternative": step.alternative,
|
|
"fields": fields,
|
|
})
|
|
})
|
|
.collect();
|
|
needs.push(json!({
|
|
"id": need.id,
|
|
"who": need.who,
|
|
"wants": need.wants,
|
|
"enters_as": need.enters_as,
|
|
"lands_in": need.lands_in,
|
|
"handled_by": need.handled_by,
|
|
"done_when": need.done_when,
|
|
"success": need.success,
|
|
"steps": steps,
|
|
}));
|
|
if let Some(schema) = aggregates.get(&need.lands_in) {
|
|
// The simulator's shape: the states a visitor's own link
|
|
// moves to (it does not model where from).
|
|
let mut self_move_targets: Vec<String> =
|
|
self_moves(questions, &need.lands_in, &schema.initial)
|
|
.into_iter()
|
|
.map(|(_, to)| to)
|
|
.collect();
|
|
self_move_targets.dedup();
|
|
buckets.entry(need.lands_in.clone()).or_insert_with(|| {
|
|
json!({
|
|
"initial": schema.initial,
|
|
"transitions": schema.transitions,
|
|
"words": need.stage_words,
|
|
"desks": desks_over(questions, &need.lands_in).iter().map(|d| json!({
|
|
"page": d.page,
|
|
"group": d.group,
|
|
"moves": d.moves.iter().map(|(from, to, label)| json!({
|
|
"from": from, "to": to, "label": label,
|
|
})).collect::<Vec<_>>(),
|
|
})).collect::<Vec<_>>(),
|
|
"self_moves": self_move_targets,
|
|
})
|
|
});
|
|
}
|
|
}
|
|
json!({
|
|
"needs": needs,
|
|
"buckets": buckets,
|
|
"personas": file.personas.iter().map(|p| json!({
|
|
"id": p.id, "need": p.need, "text": plain(&p.text),
|
|
})).collect::<Vec<_>>(),
|
|
})
|
|
}
|
|
|
|
/// One decision for the answering engine - the shape is laya's
|
|
/// `predict(state, questions)` input, so an adapter is a loop and
|
|
/// nothing more; any other engine reads the same fields.
|
|
#[derive(Debug, Serialize)]
|
|
pub struct Task {
|
|
pub id: String,
|
|
pub persona: String,
|
|
pub need: String,
|
|
pub page: String,
|
|
pub state: BTreeMap<&'static str, String>,
|
|
pub questions: BTreeMap<&'static str, ChoiceQuestion>,
|
|
/// Every alternative that still meets the need from here. The
|
|
/// engine never sees this.
|
|
pub expect: Vec<String>,
|
|
}
|
|
|
|
#[derive(Debug, Serialize)]
|
|
pub struct ChoiceQuestion {
|
|
#[serde(rename = "type")]
|
|
pub kind: &'static str,
|
|
pub instructions: String,
|
|
pub criteria: BTreeMap<String, String>,
|
|
}
|
|
|
|
fn plain(text: &str) -> String {
|
|
text.split_whitespace().collect::<Vec<_>>().join(" ")
|
|
}
|
|
|
|
/// A card a visitor can act on: it leads to a page, records an
|
|
/// answer, or moves a record. A card with none of those is read, not
|
|
/// picked - the opener that says what the business does, the look
|
|
/// around - and is context on the page, never an option.
|
|
pub fn leads_somewhere(a: &Alternative) -> bool {
|
|
a.action.is_some() || a.record_as.is_some() || a.self_transition.is_some()
|
|
}
|
|
|
|
/// What the page says before its options: every card that leads
|
|
/// nowhere, its heading, description and features, as one line each.
|
|
pub fn page_context(page: &Question) -> String {
|
|
page.alternatives
|
|
.iter()
|
|
.filter(|a| !a.disabled && !leads_somewhere(a))
|
|
.map(|a| {
|
|
let mut line = a.name.clone();
|
|
let description = plain(&a.description);
|
|
if !description.is_empty() {
|
|
line.push_str(&format!(": {description}"));
|
|
}
|
|
for f in &a.features {
|
|
let text = plain(&f.description);
|
|
match (f.name.trim().is_empty(), text.is_empty()) {
|
|
(true, true) => {}
|
|
(true, false) => line.push_str(&format!(" {text}")),
|
|
(false, true) => line.push_str(&format!(" {}.", f.name.trim())),
|
|
(false, false) => line.push_str(&format!(" {}: {text}", f.name.trim())),
|
|
}
|
|
}
|
|
line
|
|
})
|
|
.collect::<Vec<_>>()
|
|
.join("\n")
|
|
}
|
|
|
|
/// Every (persona, page-on-their-path) pair with a real choice on it.
|
|
/// `skim` shows the engine only each alternative's heading - what a
|
|
/// visitor who never reads the description has to go on.
|
|
pub fn tasks(file: &NeedsFile, questions: &Questions, skim: bool) -> Vec<Task> {
|
|
let mut out = Vec::new();
|
|
for persona in &file.personas {
|
|
let Some(need) = file.needs.iter().find(|n| n.id == persona.need) else {
|
|
continue;
|
|
};
|
|
let Some(path) = path_for(questions, need) else {
|
|
continue;
|
|
};
|
|
for (i, step) in path.iter().enumerate() {
|
|
let page = &questions[&step.page];
|
|
let open: Vec<&Alternative> = page
|
|
.alternatives
|
|
.iter()
|
|
.filter(|a| !a.disabled && leads_somewhere(a))
|
|
.collect();
|
|
if open.len() < 2 {
|
|
continue;
|
|
}
|
|
let context = page_context(page);
|
|
let mut trail: Vec<String> = path[..=i].iter().map(|s| s.page.clone()).collect();
|
|
let expect: Vec<String> = viable(
|
|
questions,
|
|
need,
|
|
page,
|
|
need.max_steps - i,
|
|
i == 0,
|
|
false,
|
|
&mut trail,
|
|
)
|
|
.into_iter()
|
|
.map(|v| v.alternative)
|
|
.collect();
|
|
let criteria = open
|
|
.iter()
|
|
.map(|a| {
|
|
let description = plain(&a.description);
|
|
(
|
|
a.name.clone(),
|
|
if skim || description.is_empty() {
|
|
a.name.clone()
|
|
} else {
|
|
description
|
|
},
|
|
)
|
|
})
|
|
.collect();
|
|
out.push(Task {
|
|
id: format!("{}@{}", persona.id, step.page),
|
|
persona: persona.id.clone(),
|
|
need: need.id.clone(),
|
|
page: step.page.clone(),
|
|
state: if context.is_empty() {
|
|
BTreeMap::from([("body", plain(&persona.text))])
|
|
} else {
|
|
BTreeMap::from([("body", plain(&persona.text)), ("page", context)])
|
|
},
|
|
questions: BTreeMap::from([(
|
|
"pick",
|
|
ChoiceQuestion {
|
|
kind: "choice",
|
|
instructions: format!(
|
|
"A visitor reads the page question {:?}. Which alternative do they choose?",
|
|
page.name
|
|
),
|
|
criteria,
|
|
},
|
|
)]),
|
|
expect,
|
|
});
|
|
}
|
|
}
|
|
out
|
|
}
|
|
|
|
#[derive(Debug, Deserialize)]
|
|
pub struct Answer {
|
|
pub id: String,
|
|
pub choice: String,
|
|
#[serde(default)]
|
|
pub confidence: Option<f64>,
|
|
}
|
|
|
|
#[derive(Debug, Default)]
|
|
pub struct Score {
|
|
pub total: usize,
|
|
pub correct: usize,
|
|
/// (task id, picked, expected, confidence)
|
|
pub misroutes: Vec<(String, String, Vec<String>, Option<f64>)>,
|
|
/// Right, but the engine was under `hesitant_below` - wording that
|
|
/// works and is still close to a coin flip.
|
|
pub hesitant: Vec<(String, f64)>,
|
|
pub unanswered: Vec<String>,
|
|
}
|
|
|
|
impl Score {
|
|
pub fn accuracy(&self) -> f64 {
|
|
if self.total == 0 {
|
|
1.0
|
|
} else {
|
|
self.correct as f64 / self.total as f64
|
|
}
|
|
}
|
|
}
|
|
|
|
pub fn score(tasks: &[Task], answers: &[Answer], hesitant_below: f64) -> Score {
|
|
let by_id: HashMap<&str, &Answer> = answers.iter().map(|a| (a.id.as_str(), a)).collect();
|
|
let mut score = Score {
|
|
total: tasks.len(),
|
|
..Score::default()
|
|
};
|
|
for task in tasks {
|
|
match by_id.get(task.id.as_str()) {
|
|
None => score.unanswered.push(task.id.clone()),
|
|
Some(answer) if task.expect.contains(&answer.choice) => {
|
|
score.correct += 1;
|
|
if let Some(c) = answer.confidence.filter(|c| *c < hesitant_below) {
|
|
score.hesitant.push((task.id.clone(), c));
|
|
}
|
|
}
|
|
Some(answer) => score.misroutes.push((
|
|
task.id.clone(),
|
|
answer.choice.clone(),
|
|
task.expect.clone(),
|
|
answer.confidence,
|
|
)),
|
|
}
|
|
}
|
|
score
|
|
}
|
|
|
|
#[cfg(test)]
|
|
mod tests {
|
|
use super::*;
|
|
use crate::aggregates::parse_aggregates_yaml;
|
|
use crate::content::build_questions;
|
|
|
|
fn site(desk_moves: &str) -> (Questions, HashMap<String, AggregateSchema>) {
|
|
let files = vec![
|
|
(
|
|
"index.yaml".to_string(),
|
|
"name: What are you here for?\nresponsible: { name: A, contact: a@b.c }\nalternatives:\n - name: Hire us\n description: Bring a problem.\n action: /thanks\n record_as: projects\n features:\n - name: Brief\n requirements:\n - name: email\n type: email\n - name: brief\n type: textarea\n - name: budget\n optional: true\n - name: Follow along\n description: Notes by mail.\n action: /thanks\n record_as: subscribers\n".to_string(),
|
|
),
|
|
("thanks.yaml".to_string(), "name: Thanks\nfollowup: true\n".to_string()),
|
|
(
|
|
"desk/index.yaml".to_string(),
|
|
format!("name: Desk\nqualifies: owners\nalternatives:\n - name: Projects\n features:\n - name: \"\"\n resource:\n source: {{ kind: kv, bucket: projects }}\n requires_group: owners\n transitions:\n{desk_moves}"),
|
|
),
|
|
];
|
|
let aggregates = parse_aggregates_yaml(
|
|
"aggregates:\n - bucket: projects\n initial: open\n states:\n open: { event: submitted }\n quoted: { event: quoted }\n won: { event: won }\n lost: { event: lost }\n transitions:\n open: [quoted, lost]\n quoted: [won, lost]\n - bucket: subscribers\n attended_by: a mailer\n initial: open\n states:\n open: { event: subscribed }\n transitions: {}\n",
|
|
)
|
|
.unwrap();
|
|
(build_questions(&files).unwrap(), aggregates)
|
|
}
|
|
|
|
const FULL_DESK: &str = " - { to: quoted, label: Quote }\n - { to: lost, label: Lose }\n - { from: quoted, to: won, label: Win }\n - { from: quoted, to: lost, label: Lose }\n";
|
|
|
|
fn needs(extra: &str) -> NeedsFile {
|
|
parse(&format!(
|
|
"needs:\n - id: hire\n who: a client\n wants: work done\n lands_in: projects\n handled_by: owners\n done_when: [won, lost]\n{extra}personas:\n - id: founder\n need: hire\n text: I need someone to build our booking tool.\n"
|
|
))
|
|
.unwrap()
|
|
}
|
|
|
|
fn fails(findings: &[Finding]) -> Vec<&str> {
|
|
findings
|
|
.iter()
|
|
.filter(|f| f.level == Level::Fail)
|
|
.map(|f| f.message.as_str())
|
|
.collect()
|
|
}
|
|
|
|
#[test]
|
|
fn a_met_need_is_silent() {
|
|
let (questions, aggregates) = site(FULL_DESK);
|
|
let findings = check(&needs(" max_fields: 2\n"), &questions, &aggregates);
|
|
assert!(findings.is_empty(), "{findings:?}");
|
|
}
|
|
|
|
#[test]
|
|
fn effort_budget_counts_required_fields_only() {
|
|
let (questions, aggregates) = site(FULL_DESK);
|
|
let findings = check(&needs(" max_fields: 1\n"), &questions, &aggregates);
|
|
assert_eq!(
|
|
fails(&findings),
|
|
vec!["the path asks for 2 required field(s), over the budget of 1"]
|
|
);
|
|
// A field that carries rather than asks is not effort: the
|
|
// record an answer is about arrives on the link.
|
|
let (mut questions, aggregates) = site(FULL_DESK);
|
|
let front = questions.get_mut("/").unwrap();
|
|
let brief = &mut front.alternatives[0].features[0].requirements;
|
|
let mut carrier = brief[0].clone();
|
|
carrier.name = "case".into();
|
|
carrier.kind = "record".into();
|
|
carrier.of = Some("projects".into());
|
|
carrier.optional = false;
|
|
brief.push(carrier);
|
|
let findings = check(&needs(" max_fields: 2\n"), &questions, &aggregates);
|
|
assert!(fails(&findings).is_empty(), "{findings:?}");
|
|
}
|
|
|
|
#[test]
|
|
fn a_desk_missing_a_move_strands_records_and_cannot_finish() {
|
|
// The desk can quote, but never close a quoted job.
|
|
let (questions, aggregates) = site(
|
|
" - { to: quoted, label: Quote }\n - { to: lost, label: Lose }\n",
|
|
);
|
|
let findings = check(&needs(""), &questions, &aggregates);
|
|
assert_eq!(
|
|
fails(&findings),
|
|
vec![
|
|
"\"owners\" cannot move a record to \"won\" - no desk of theirs offers the moves - fix: add `{ from: quoted, to: won, label: ... }` to the transitions on /desk",
|
|
"records strand in \"quoted\": \"owners\" is offered no move out of it - fix: add `{ from: quoted, to: won, label: ... }` to the transitions on /desk",
|
|
]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_finished_state_may_lead_on_to_another() {
|
|
// quoted counts as handled here, yet won must still be
|
|
// reachable past it; lost-after-quoted is not this need's
|
|
// business, so nothing strands.
|
|
let (questions, aggregates) = site(FULL_DESK);
|
|
let mut file = needs("");
|
|
file.needs[0].done_when = vec!["quoted".to_string(), "won".to_string(), "lost".to_string()];
|
|
let findings = check(&file, &questions, &aggregates);
|
|
assert!(findings.is_empty(), "{findings:?}");
|
|
}
|
|
|
|
#[test]
|
|
fn a_disabled_alternative_is_named_as_the_reason() {
|
|
let (mut questions, aggregates) = site(FULL_DESK);
|
|
questions.get_mut("/").unwrap().alternatives[0].disabled = true;
|
|
let findings = check(&needs(""), &questions, &aggregates);
|
|
assert_eq!(
|
|
fails(&findings),
|
|
vec!["the path exists but is closed: \"Hire us\" on / is `disabled`, so the answer is advertised and refused"]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn success_must_be_a_finished_state_and_the_sim_model_carries_the_whole_flow() {
|
|
let (questions, aggregates) = site(FULL_DESK);
|
|
let mut file = needs(" success: [won]\n");
|
|
assert!(check(&file, &questions, &aggregates).is_empty());
|
|
|
|
let model = sim_model(&file, &questions, &aggregates);
|
|
let need = &model["needs"][0];
|
|
assert_eq!(need["success"][0], "won");
|
|
let step = &need["steps"][0];
|
|
assert_eq!(step["question"], "What are you here for?");
|
|
assert_eq!(step["expect"][0], "Hire us");
|
|
assert_eq!(step["options"].as_array().unwrap().len(), 2);
|
|
// The form the visitor fills, required and optional alike.
|
|
let fields = step["fields"].as_array().unwrap();
|
|
assert_eq!(fields.len(), 3);
|
|
assert_eq!(fields[2]["optional"], true);
|
|
// The desk's buttons, labelled, per state.
|
|
let moves = model["buckets"]["projects"]["desks"][0]["moves"]
|
|
.as_array()
|
|
.unwrap();
|
|
assert!(moves
|
|
.iter()
|
|
.any(|m| m["from"] == "quoted" && m["to"] == "won" && m["label"] == "Win"));
|
|
assert_eq!(model["buckets"]["projects"]["initial"], "open");
|
|
assert_eq!(model["personas"][0]["id"], "founder");
|
|
|
|
// A stage the business named must exist as a state.
|
|
file.needs[0].stages = vec!["open".into(), "surveyed".into(), "quoted".into()];
|
|
assert_eq!(
|
|
fails(&check(&file, &questions, &aggregates)),
|
|
vec!["the business describes a stage \"surveyed\" that \"projects\" has no state for"]
|
|
);
|
|
file.needs[0].stages = vec!["open".into(), "quoted".into(), "won".into()];
|
|
assert!(check(&file, &questions, &aggregates).is_empty());
|
|
|
|
file.needs[0].success = vec!["quoted".to_string()];
|
|
assert_eq!(
|
|
fails(&check(&file, &questions, &aggregates)),
|
|
vec!["success names \"quoted\", which is not one of done_when"]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_need_can_be_carried_by_more_than_one_groups_desk() {
|
|
// owners may only quote or lose; closing a quoted job is the
|
|
// site managers' button, on a desk of their own.
|
|
let (mut questions, aggregates) = site(
|
|
" - { to: quoted, label: Quote }\n - { to: lost, label: Lose }\n",
|
|
);
|
|
let more = build_questions(&[(
|
|
"site/index.yaml".to_string(),
|
|
"name: Site desk\nqualifies: site_managers\nalternatives:\n - name: Projects\n features:\n - name: \"\"\n resource:\n source: { kind: kv, bucket: projects }\n requires_group: site_managers\n transitions:\n - { from: quoted, to: won, label: Win }\n - { from: quoted, to: lost, label: Lose }\n".to_string(),
|
|
)])
|
|
.unwrap();
|
|
questions.extend(more);
|
|
|
|
let mut file = needs("");
|
|
// Alone, owners cannot finish it...
|
|
assert_eq!(fails(&check(&file, &questions, &aggregates)).len(), 2);
|
|
// ...with the site managers' buttons counted, they can.
|
|
file.needs[0].also_moved_by = vec!["site_managers".to_string()];
|
|
assert!(check(&file, &questions, &aggregates).is_empty());
|
|
// But someone has to be answerable: handled_by needs its own desk.
|
|
file.needs[0].handled_by = "nobody".to_string();
|
|
assert!(fails(&check(&file, &questions, &aggregates))[0]
|
|
.starts_with("no desk gated on \"nobody\""));
|
|
}
|
|
|
|
#[test]
|
|
fn the_wrong_group_holding_the_desk_is_a_failure() {
|
|
let (questions, aggregates) = site(FULL_DESK);
|
|
let mut file = needs("");
|
|
file.needs[0].handled_by = "sales".to_string();
|
|
let findings = check(&file, &questions, &aggregates);
|
|
assert_eq!(
|
|
fails(&findings),
|
|
vec!["no desk gated on \"sales\" reads \"projects\" - it is read by /desk (owners)"]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn via_pins_the_entry_alternative() {
|
|
let (questions, aggregates) = site(FULL_DESK);
|
|
let mut file = needs("");
|
|
file.needs[0].via = Some("Follow along".to_string());
|
|
let findings = check(&file, &questions, &aggregates);
|
|
assert_eq!(
|
|
fails(&findings),
|
|
vec!["no path from \"/\" via \"Follow along\" records into \"projects\" within 2 submission(s)"]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn tasks_carry_the_page_as_a_choice_and_score_separates_misroutes() {
|
|
let (questions, _) = site(FULL_DESK);
|
|
let file = needs("");
|
|
let tasks = tasks(&file, &questions, false);
|
|
let skimmed = super::tasks(&file, &questions, true);
|
|
assert_eq!(
|
|
skimmed[0].questions["pick"].criteria["Follow along"],
|
|
"Follow along"
|
|
);
|
|
assert_eq!(tasks.len(), 1);
|
|
let task = &tasks[0];
|
|
assert_eq!(task.id, "founder@/");
|
|
assert_eq!(task.expect, vec!["Hire us"]);
|
|
let q = &task.questions["pick"];
|
|
assert_eq!(q.kind, "choice");
|
|
assert_eq!(q.criteria["Follow along"], "Notes by mail.");
|
|
assert!(q.instructions.contains("What are you here for?"));
|
|
|
|
let right = vec![Answer {
|
|
id: "founder@/".into(),
|
|
choice: "Hire us".into(),
|
|
confidence: Some(0.55),
|
|
}];
|
|
let s = score(&tasks, &right, 0.6);
|
|
assert_eq!((s.correct, s.misroutes.len(), s.hesitant.len()), (1, 0, 1));
|
|
|
|
let wrong = vec![Answer {
|
|
id: "founder@/".into(),
|
|
choice: "Follow along".into(),
|
|
confidence: Some(0.9),
|
|
}];
|
|
let s = score(&tasks, &wrong, 0.6);
|
|
assert_eq!((s.correct, s.misroutes.len()), (0, 1));
|
|
assert_eq!(s.accuracy(), 0.0);
|
|
|
|
assert_eq!(score(&tasks, &[], 0.6).unanswered, vec!["founder@/"]);
|
|
}
|
|
|
|
/// The fixture site with its aggregates replaced, for the checks
|
|
/// that are about the state machine rather than the pages.
|
|
fn site_with(
|
|
desk_moves: &str,
|
|
projects: &str,
|
|
) -> (Questions, HashMap<String, AggregateSchema>) {
|
|
let (questions, _) = site(desk_moves);
|
|
let aggregates = parse_aggregates_yaml(&format!(
|
|
"aggregates:\n - bucket: projects\n{projects} - bucket: subscribers\n attended_by: a mailer\n initial: open\n states:\n open: {{ event: subscribed }}\n transitions: {{}}\n"
|
|
))
|
|
.unwrap();
|
|
(questions, aggregates)
|
|
}
|
|
|
|
fn warns(findings: &[Finding]) -> Vec<&str> {
|
|
findings
|
|
.iter()
|
|
.filter(|f| f.level == Level::Warn)
|
|
.map(|f| f.message.as_str())
|
|
.collect()
|
|
}
|
|
|
|
#[test]
|
|
fn a_clock_is_a_move() {
|
|
// Nobody closes a stale quote; six weeks do. That is not a strand.
|
|
let (questions, aggregates) = site_with(
|
|
" - { to: quoted, label: Quote }\n - { from: quoted, to: won, label: Win }\n",
|
|
" initial: open\n states:\n open: { event: submitted }\n quoted: { event: quoted, after: { days: 42, to: lost } }\n won: { event: won }\n lost: { event: lost }\n transitions:\n open: [quoted]\n quoted: [won, lost]\n",
|
|
);
|
|
let findings = check(&needs(""), &questions, &aggregates);
|
|
assert!(fails(&findings).is_empty(), "{findings:?}");
|
|
}
|
|
|
|
#[test]
|
|
fn a_state_nobody_reaches_and_a_strand_after_done_are_the_buckets() {
|
|
// "archived" follows "won" but no desk offers it; "parked" has
|
|
// no way in at all.
|
|
let (questions, aggregates) = site_with(
|
|
FULL_DESK,
|
|
" initial: open\n states:\n open: { event: submitted }\n quoted: { event: quoted }\n won: { event: won }\n lost: { event: lost }\n archived: { event: archived }\n done: { event: done }\n parked: { event: parked }\n transitions:\n open: [quoted, lost]\n quoted: [won, lost]\n won: [archived]\n archived: [done]\n parked: [open]\n",
|
|
);
|
|
let findings = check(&needs(""), &questions, &aggregates);
|
|
let bucket: Vec<&Finding> = findings.iter().filter(|f| f.scope == "bucket").collect();
|
|
assert!(bucket.iter().all(|f| f.need == "projects"), "{bucket:?}");
|
|
assert_eq!(
|
|
fails(&findings),
|
|
vec![
|
|
"state \"archived\" is never reached: no desk, link or clock moves a record there - fix: add `{ from: won, to: archived, label: ... }` to the transitions on /desk",
|
|
"state \"done\" is never reached: no desk, link or clock moves a record there - fix: declare an edge into it from a state records reach in aggregates.yaml, or remove it",
|
|
"state \"parked\" is never reached: no desk, link or clock moves a record there - fix: declare an edge into it from a state records reach in aggregates.yaml, or remove it",
|
|
"records strand in \"won\": \"projects\" declares moves on to archived but no desk, link or clock offers one - fix: add `{ from: won, to: archived, label: ... }` to the transitions on /desk",
|
|
]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn an_edge_nobody_offers_is_a_warning_when_there_is_another_way_on() {
|
|
let (questions, aggregates) = site(" - { to: quoted, label: Quote }\n - { from: quoted, to: won, label: Win }\n - { from: quoted, to: lost, label: Lose }\n");
|
|
let findings = check(&needs(""), &questions, &aggregates);
|
|
assert!(fails(&findings).is_empty(), "{findings:?}");
|
|
assert_eq!(
|
|
warns(&findings),
|
|
vec!["the move \"open\" -> \"lost\" is declared but no desk, link or clock offers it - fix: add `{ from: open, to: lost, label: ... }` to the transitions on /desk, or drop the edge from aggregates.yaml"]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn working_stages_must_follow_each_other() {
|
|
// The business surveys, then quotes; this machine can only
|
|
// quote straight from open, and surveying leads nowhere.
|
|
let (questions, aggregates) = site_with(
|
|
" - { to: quoted, label: Quote }\n - { to: surveyed, label: Survey }\n - { from: surveyed, to: lost, label: Lose }\n - { from: quoted, to: won, label: Win }\n - { from: quoted, to: lost, label: Lose }\n",
|
|
" initial: open\n states:\n open: { event: submitted }\n surveyed: { event: surveyed }\n quoted: { event: quoted }\n won: { event: won }\n lost: { event: lost }\n transitions:\n open: [surveyed, quoted]\n surveyed: [lost]\n quoted: [won, lost]\n",
|
|
);
|
|
let findings = check(
|
|
&needs(" stages: [open, surveyed, quoted, won, lost]\n"),
|
|
&questions,
|
|
&aggregates,
|
|
);
|
|
assert_eq!(
|
|
fails(&findings),
|
|
vec!["stage \"quoted\" comes after \"surveyed\" for the business, but no move leads on from \"surveyed\" to it - fix: add an edge from \"surveyed\" toward \"quoted\" in aggregates.yaml under \"projects\""]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_mail_may_only_say_what_the_record_holds() {
|
|
let (questions, aggregates) = site_with(
|
|
FULL_DESK,
|
|
" initial: open\n states:\n open: { event: submitted, mail: { to: submitter, subject: 'Got it, {email}', body: 'We read {brief} and will reply at {site}. {refnr} {link}' } }\n quoted: { event: quoted }\n won: { event: won }\n lost: { event: lost }\n transitions:\n open: [quoted, lost]\n quoted: [won, lost]\n",
|
|
);
|
|
let findings = check(&needs(""), &questions, &aggregates);
|
|
assert_eq!(
|
|
fails(&findings),
|
|
vec!["the mail on entering \"open\" uses {refnr}, which no form recording into \"projects\" collects, so it would go out blank there - fix: use one of the fields the forms collect (brief, budget, email), or ask for it on the form"]
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_desk_gated_twice_is_seen_only_by_members_of_both() {
|
|
let (mut questions, aggregates) = site(FULL_DESK);
|
|
questions.get_mut("/desk").unwrap().qualifies = Some("staff".into());
|
|
let findings = check(&needs(""), &questions, &aggregates);
|
|
assert!(
|
|
warns(&findings).contains(&"the desk on /desk is gated twice: the page qualifies \"staff\", its list requires \"owners\", so only members of both see the buttons - fix: make them the same group"),
|
|
"{findings:?}"
|
|
);
|
|
}
|
|
|
|
#[test]
|
|
fn a_finding_keeps_its_id_when_reworded_and_says_its_fix() {
|
|
let (questions, aggregates) = site(
|
|
" - { to: quoted, label: Quote }\n - { to: lost, label: Lose }\n",
|
|
);
|
|
let findings = check(&needs(""), &questions, &aggregates);
|
|
let strand = findings.iter().find(|f| f.code == "strand").unwrap();
|
|
assert_eq!(strand.subject, "quoted");
|
|
assert_eq!(
|
|
strand.fix(),
|
|
Some("add `{ from: quoted, to: won, label: ... }` to the transitions on /desk")
|
|
);
|
|
let reworded = Finding {
|
|
message: "something else entirely".into(),
|
|
..clone_of(strand)
|
|
};
|
|
assert_eq!(reworded.id(), strand.id());
|
|
let elsewhere = Finding {
|
|
subject: "open".into(),
|
|
..clone_of(strand)
|
|
};
|
|
assert_ne!(elsewhere.id(), strand.id());
|
|
let json = strand.to_json();
|
|
assert_eq!(json["code"], "strand");
|
|
assert_eq!(json["level"], "fail");
|
|
assert_eq!(json["id"], strand.id());
|
|
}
|
|
|
|
fn clone_of(f: &Finding) -> Finding {
|
|
Finding {
|
|
need: f.need.clone(),
|
|
level: f.level,
|
|
message: f.message.clone(),
|
|
scope: f.scope,
|
|
code: f.code,
|
|
subject: f.subject.clone(),
|
|
}
|
|
}
|
|
}
|