~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
2634 lines · 113.0 KB Raw History
//! The operator's apps (`HUD_APPS`): a directory of apps HUD serves beside
//! its bundled views. Each app is a file at its top named for its domain,
//! `<domain>.json`: its name, tabs and routes, each tab and route a tool
//! call, as the app's clients draw it (they bundle their own copy), how
//! its clients register a device for push (`push`), what HUD calls
//! after a write of the app's records for its server to read them back at
//! once (`refresh`, sent by `Hud::refresh_written`), and the permission
//! sets sign-in asks for (`permissions`, `scope::including`). The views are
//! `views/<id>.json` beside the apps, each a `place.hud.view`, and the
//! lexicons the apps ship, `lexicons/` (`lexicons_of`). A file at
//! the top whose name holds no dot (`package.json`) is no app, so the
//! directory can be a client's own. An app file may say which HUD
//! versions it runs on (`hud`, a semver requirement as `>=0.2.0`), and
//! one needing a newer HUD is refused before anything else is checked
//! (`version_problem`). It may say the oldest kit its clients' builds
//! still draw with (`kits.oldest`): the operator's views are read for what
//! that kit would not draw, each a warning (`kit::warnings`).
//!
//! HUD trusts the operator's views as it does its bundled ones: their
//! calls and query joins are sent. So it holds them, as it starts, to
//! what the tests hold the bundled ones to, and refuses to start if any
//! file falls short, naming every problem (`check`; `hud check` prints
//! them): each parsed as a trusted view (its optional keys, `?key`, left
//! out where they fall short, with a warning: `view::load`), its calls,
//! query joins and profile section against the apps' lexicons and HUD's
//! bundled ones (`view::trusted_problems`, `Views::lexicon_docs`), none
//! drawing what another draws
//! (`view::conflicts`), and each app's tabs and routes calling what a view
//! draws, a tab's root chosen from the account's data (`first`) what
//! `place.hud.tabFirst` describes, its push calls procedures HUD has
//! lexicons for, its frame
//! (how its clients' shells draw it) what `place.hud.frame` describes,
//! and its pages each what `place.hud.page` does, at a path no other
//! screen has, its Markdown's file there, and its sign-in screen
//! (`signIn`) what `place.hud.signIn` does (`app_problems`, `pages_of`).
//! An operator's view replaces the bundled view of its
//! id, and any drawing what it draws (`view::Views::with`); an app's
//! lexicon the bundled one of its NSID (`view::Views::lexicon`); an app's push
//! calls are sent by `call_procedure` as a trusted view's are
//! (`view::Views::with_pushes`); an app with a `signIn` has its web
//! clients sent straight on to the account's server
//! (`view::Views::sign_ins`); and an app's permission sets are asked for
//! first at sign-in (`view::Views::sets`).

use crate::catalog::FRAME_ICONS;
use crate::scope::Include;
use crate::view::{self, Views};
use atproto::lexicon::Lexicons;
use serde_json::{Value, json};
use std::collections::BTreeSet;
use std::path::{Path, PathBuf};
use std::sync::{Arc, LazyLock};

/// The values a push call's input binds, each `{"$…": true}`, which the
/// client stamps as it registers: the device's token, the app's id (its
/// bundle id) and its platform (`ios`).
pub const PUSH_BINDINGS: [&str; 3] = ["$token", "$appId", "$platform"];

/// The operator's apps, checked: the trusted views with theirs, the apps'
/// domains, the operator's views' ids, and what HUD warns of as it loads
/// them (a view's optional keys it leaves out, `view::load`).
#[derive(Debug)]
pub struct Loaded {
    pub views: Views,
    pub apps: Vec<String>,
    pub ids: Vec<String>,
    pub warnings: Vec<String>,
}

/// This HUD's version, which an app file's `hud` is held to.
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

/// A file's text, or why it can't be read, naming it.
fn read(path: &Path) -> Result<String, String> {
    std::fs::read_to_string(path).map_err(|e| format!("{}: {e}", path.display()))
}

/// A JSON file's document, or why it can't be read, naming it.
fn read_json(path: &Path) -> Result<Value, String> {
    let text = read(path)?;
    serde_json::from_str(&text).map_err(|e| format!("{}: {e}", path.display()))
}

/// The `.json` files directly in `dir`, sorted, each with its name before
/// `.json`; none where `dir` is no directory.
fn json_files(dir: &Path) -> Vec<(String, PathBuf)> {
    let mut out: Vec<(String, PathBuf)> = std::fs::read_dir(dir)
        .into_iter()
        .flatten()
        .flatten()
        .map(|e| e.path())
        .filter(|p| p.is_file() && p.extension().is_some_and(|x| x == "json"))
        .filter_map(|p| Some((p.file_stem()?.to_str()?.to_string(), p)))
        .collect();
    out.sort();
    out
}

/// The operator's apps in `dir`, checked against the lexicons they ship
/// and HUD's and, with `bundled`, beside the bundled views, which they
/// replace and add to; else alone, as an instance serving its operator's
/// apps alone (no workspace) serves them. Or every problem, each naming
/// its file and where in it.
pub fn load(dir: &Path, bundled: bool) -> Result<Loaded, Vec<String>> {
    let version = semver::Version::parse(VERSION).expect("HUD's version is semver");
    load_as(dir, bundled, &version)
}

/// `load`, as the HUD of `version`.
fn load_as(dir: &Path, bundled: bool, version: &semver::Version) -> Result<Loaded, Vec<String>> {
    if let Err(e) = std::fs::read_dir(dir) {
        return Err(vec![format!("{}: {e}", dir.display())]);
    }
    let apps: Vec<(String, PathBuf)> = json_files(dir)
        .into_iter()
        .filter(|(name, _)| name.contains('.'))
        .collect();
    let files = json_files(&dir.join("views"));
    if apps.is_empty() && files.is_empty() {
        return Err(vec![format!(
            "{}: no app (<domain>.json) and no view (views/<id>.json)",
            dir.display()
        )]);
    }
    let mut problems = Vec::new();
    let mut docs = Vec::new();
    for (domain, path) in &apps {
        match read_json(path) {
            Ok(doc) => docs.push((domain, path.display().to_string(), doc)),
            Err(e) => problems.push(e),
        }
    }
    // An app needing a newer HUD is all there is to say: the rest of it
    // is written for that HUD.
    let newer: Vec<String> = docs
        .iter()
        .filter_map(|(_, file, doc)| Some(format!("{file}: {}", version_problem(doc, version)?)))
        .collect();
    if !newer.is_empty() {
        return Err(newer);
    }
    let (lexicons, wrong) = lexicons_of(&dir.join("lexicons"));
    problems.extend(wrong);
    let mut texts = Vec::new();
    for (id, path) in &files {
        match read(path) {
            Ok(text) => texts.push((id, path.display().to_string(), text)),
            Err(e) => problems.push(e),
        }
    }
    let built = match bundled {
        true => Views::built_in(),
        false => Views::none(),
    };
    let view_docs: Vec<Value> = texts
        .iter()
        .filter_map(|(_, _, text)| serde_json::from_str(text).ok())
        .collect();
    let mut services = view::services_of(&view_docs);
    services.extend_from_slice(built.services());
    let (mut added, mut warnings) = (Vec::new(), Vec::new());
    for (id, file, text) in texts {
        match view::load(file, id, &text, &services) {
            Ok((b, left_out)) => {
                added.push(b);
                warnings.extend(left_out);
            }
            Err(wrong) => problems.extend(wrong),
        }
    }
    let ids: Vec<String> = added.iter().map(|b| b.id.clone()).collect();
    let views = built.with(added).with_lexicons(lexicons);
    problems.extend(view::conflicts(views.all()));
    let lexicons = views.lexicon_docs();
    for b in views.all().iter().filter(|b| ids.contains(&b.id)) {
        let wrong = view::trusted_problems(&b.view, &lexicons, &views);
        problems.extend(wrong.into_iter().map(|p| format!("{}: {p}", b.file)));
    }
    // An app's own collections, whose writes its `refresh` is called for:
    // those the operator's views write, or plan to delete.
    let mut own = views.written_by(&|b| ids.contains(&b.id));
    let operators = views.all().iter().filter(|b| ids.contains(&b.id));
    own.extend(
        operators
            .flat_map(|b| &b.view.plans)
            .flat_map(|p| p.collections.iter().cloned()),
    );
    let (mut pushes, mut refreshes, mut pages) = (Vec::new(), Vec::new(), Vec::new());
    let (mut sign_ins, mut sets) = (Vec::new(), Vec::new());
    for (domain, file, doc) in &docs {
        let wrong = app_problems(doc, domain, &views);
        if !wrong.is_empty() {
            problems.extend(wrong.iter().map(|p| format!("{file}: {p}")));
            continue;
        }
        pushes.extend(push_calls(doc));
        refreshes.extend(refresh_of(doc, &own));
        sets.extend(sets_of(doc));
        match pages_of(doc, domain, dir) {
            Ok(found) => pages.extend(found),
            Err(e) => problems.push(format!("{file}: {e}")),
        }
        if doc.get("signIn").is_some() {
            sign_ins.push(domain.to_string());
        }
    }
    if !problems.is_empty() {
        return Err(problems);
    }
    // What the oldest kit the apps serve would not draw, where they say.
    if let Some(oldest) = docs.iter().filter_map(|(_, _, doc)| oldest_kit(doc)).min() {
        for b in views.all().iter().filter(|b| ids.contains(&b.id)) {
            warnings.extend(crate::kit::warnings(&b.file, &b.view.doc, &oldest));
        }
    }
    let apps = apps.into_iter().map(|(domain, _)| domain).collect();
    let views = views
        .with_pushes(pushes)
        .with_refreshes(refreshes)
        .with_pages(pages)
        .with_sign_ins(sign_ins)
        .with_sets(sets);
    Ok(Loaded {
        views,
        apps,
        ids,
        warnings,
    })
}

/// The oldest kit an app file's clients serve (`kits.oldest`), where it
/// says.
fn oldest_kit(doc: &Value) -> Option<semver::Version> {
    semver::Version::parse(doc["kits"]["oldest"].as_str()?).ok()
}

/// What is wrong with an app file's `kits`: `{ oldest }`, the oldest kit
/// (a HUD version, no older than `kit::OLDEST`) its clients still serve,
/// which `hud check` holds its views to (`kit::warnings`).
fn kits_problems(kits: &Value, out: &mut Vec<String>) {
    let first = semver::Version::parse(crate::kit::OLDEST).expect("the oldest kit is semver");
    let one = kits.as_object().is_some_and(|o| o.len() == 1);
    if !one || oldest_kit(&json!({ "kits": kits })).is_none_or(|v| v < first) {
        out.push(format!(
            "app.kits: must be {{ oldest }}, the oldest kit its clients still serve, a HUD version from {first}, as \"{first}\""
        ));
    }
}

/// What is wrong with an app file's `hud`, the HUD versions it runs on, a
/// semver requirement (`>=0.2.0`), for the HUD of `version`: one that is no
/// requirement, or that this HUD doesn't meet. None where it names none.
fn version_problem(doc: &Value, version: &semver::Version) -> Option<String> {
    let need = doc.get("hud")?;
    let Some(req) = need
        .as_str()
        .and_then(|s| semver::VersionReq::parse(s).ok())
    else {
        return Some("app.hud: must be the HUD versions the app runs on, as \">=0.2.0\"".into());
    };
    (!req.matches(version)).then(|| {
        format!("app.hud: the app needs HUD {req}, and this HUD is {version}: run a newer HUD")
    })
}

/// The lexicons the operator's apps ship (`lexicons/`, `.json` files at
/// any depth), each a lexicon document (`lexicon: 1`, its `id` an NSID,
/// `defs`), one file of each NSID, none of HUD's own (`place.hud.*`); and
/// what is wrong with the others, naming their files. HUD reads an app's
/// lexicon in place of the bundled one of its NSID: its views were written
/// against it.
fn lexicons_of(dir: &Path) -> (Vec<Arc<Value>>, Vec<String>) {
    let mut paths = Vec::new();
    json_tree(dir, &mut paths);
    paths.sort();
    let (mut docs, mut problems) = (Vec::<Arc<Value>>::new(), Vec::new());
    for path in paths {
        let doc = match read_json(&path) {
            Ok(doc) => doc,
            Err(e) => {
                problems.push(e);
                continue;
            }
        };
        let file = path.display();
        let id = doc["id"].as_str().unwrap_or_default().to_string();
        if !atproto::syntax::is_nsid(&id) || !crate::lexicon::is_document(&doc, &id) {
            problems.push(format!(
                "{file}: must be a lexicon document: lexicon 1, an NSID as its id, and defs"
            ));
        } else if id.starts_with("place.hud.") {
            problems.push(format!(
                "{file}: {id} is HUD's own lexicon, which no app ships"
            ));
        } else if docs.iter().any(|d| d["id"] == id.as_str()) {
            problems.push(format!("{file}: another file is {id} too"));
        } else {
            docs.push(Arc::new(doc));
        }
    }
    (docs, problems)
}

/// Add to `out` the `.json` files under `dir`, at any depth; none where
/// `dir` is no directory.
fn json_tree(dir: &Path, out: &mut Vec<PathBuf>) {
    let entries = std::fs::read_dir(dir).into_iter().flatten().flatten();
    for path in entries.map(|e| e.path()) {
        if path.is_dir() {
            json_tree(&path, out);
        } else if path.extension().is_some_and(|x| x == "json") {
            out.push(path);
        }
    }
}

/// What is wrong with the app file of `domain`, as HUD reads it: an object
/// naming its domain and its name, with one or more tabs, each a label and
/// a call (and signed out, `guest`: another call, or "call" for the same;
/// signed in, `first`, if any, `first_problems`),
/// and routes, each a path, a call and the label of the tab it opens
/// under, if any; each call drawing what a view among `views` draws; its
/// `push`, if any (`push_problems`); its `head`, if any
/// (`head_problems`); its `frame`, if any (`frame_problems`); its
/// `pages`, if any (`pages_problems`); its `signIn`, if any
/// (`sign_in_problems`); and its `permissions`, if any
/// (`permissions_problems`). The
/// rest (its look, a tab's icon and badge) is its clients' alone.
pub fn app_problems(doc: &Value, domain: &str, views: &Views) -> Vec<String> {
    let Some(o) = doc.as_object() else {
        return vec!["app: must be an object".into()];
    };
    let mut out = Vec::new();
    if o.get("domain").and_then(Value::as_str) != Some(domain) {
        out.push(format!(
            "app.domain: must be {domain}, as its file is named"
        ));
    }
    if !o
        .get("name")
        .and_then(Value::as_str)
        .is_some_and(|n| !n.trim().is_empty())
    {
        out.push("app.name: required".into());
    }
    let tabs = o.get("tabs").and_then(Value::as_array);
    let tabs = tabs.map(Vec::as_slice).unwrap_or_default();
    if tabs.is_empty() {
        out.push("app.tabs: must be a list of one or more tabs".into());
    }
    let mut labels = Vec::new();
    for (i, t) in tabs.iter().enumerate() {
        let at = format!("app.tabs[{i}]");
        match t["label"].as_str() {
            Some(l) => labels.push(l),
            None => out.push(format!("{at}.label: required")),
        }
        drawn(&t["call"], &format!("{at}.call"), views, &mut out);
        if !t["guest"].is_null() && t["guest"] != "call" {
            drawn(&t["guest"], &format!("{at}.guest"), views, &mut out);
        }
        if let Some(first) = t.get("first") {
            first_problems(first, &format!("{at}.first"), &mut out);
        }
    }
    let routes = match o.get("routes") {
        None => &[][..],
        Some(Value::Array(r)) => r.as_slice(),
        Some(_) => {
            out.push("app.routes: must be a list of routes".into());
            &[]
        }
    };
    for (i, r) in routes.iter().enumerate() {
        let at = format!("app.routes[{i}]");
        if !r["path"].as_str().is_some_and(|p| p.starts_with('/')) {
            out.push(format!("{at}.path: must be a path, starting with /"));
        }
        drawn(&r["call"], &format!("{at}.call"), views, &mut out);
        if !r["tab"].is_null() && !r["tab"].as_str().is_some_and(|t| labels.contains(&t)) {
            out.push(format!("{at}.tab: must be a tab's label"));
        }
        pager_problems(r, &at, routes, &mut out);
    }
    if let Some(push) = o.get("push") {
        push_problems(push, routes, views, &mut out);
    }
    if let Some(refresh) = o.get("refresh") {
        refresh_problems(refresh, &mut out);
    }
    if let Some(permissions) = o.get("permissions") {
        permissions_problems(permissions, &mut out);
    }
    if let Some(head) = o.get("head") {
        head_problems(head, &mut out);
    }
    if let Some(frame) = o.get("frame") {
        frame_problems(frame, &labels, views, &mut out);
    }
    if let Some(pages) = o.get("pages") {
        pages_problems(pages, tabs, routes, &mut out);
    }
    if let Some(sign_in) = o.get("signIn") {
        sign_in_problems(sign_in, &mut out);
    }
    if let Some(kits) = o.get("kits") {
        kits_problems(kits, &mut out);
    }
    out
}

/// The lexicon of a tab's `first`.
const TAB_FIRST: &str = "place.hud.tabFirst";

/// The lexicon document of a tab's `first`, and its validator.
static TAB_FIRST_LEXICON: LazyLock<(Arc<Value>, Lexicons)> = LazyLock::new(|| {
    let doc =
        crate::lexicon::bundled(TAB_FIRST).expect("schemas/place.hud.tabFirst.json is bundled");
    let lexicons = Lexicons::new([(*doc).clone()]);
    (doc, lexicons)
});

/// What is wrong with a tab's `first`, at `at`: where its clients choose
/// its root from the account's data, signed in (Grain's Home, the first
/// feed pinned). It must be what its lexicon (`place.hud.tabFirst`)
/// describes, with no key it does not name; its call a query of a
/// method's NSID (its answer is data, as a badge's is); its `at` and
/// `path` dotted paths, no segment empty. Whether a listed path has a
/// screen is the clients' to find, item by item, by the app's routes.
fn first_problems(first: &Value, at: &str, out: &mut Vec<String>) {
    let (doc, lexicons) = &*TAB_FIRST_LEXICON;
    unknown(&doc["defs"], "main", first, at, out);
    if let Err(e) = lexicons.validate(TAB_FIRST, first) {
        let rest = e.path.strip_prefix("object").unwrap_or(&e.path);
        out.push(format!("{at}{rest} {}", e.message));
        return;
    }
    let call = &first["call"];
    let method = call["args"]["method"].as_str().unwrap_or_default();
    if call["name"] != "query" || !atproto::syntax::is_nsid(method) {
        out.push(format!("{at}.call: must be a query of a method's NSID"));
    }
    for key in ["at", "path"] {
        let path = first[key].as_str().unwrap_or_default();
        if path.split('.').any(str::is_empty) {
            out.push(format!(
                "{at}.{key}: must be a dotted path, no segment empty"
            ));
        }
    }
}

/// The pages' lexicon, one page's.
const PAGE: &str = "place.hud.page";

/// The page's lexicon document, and its validator.
static PAGE_LEXICON: LazyLock<(Arc<Value>, Lexicons)> = LazyLock::new(|| {
    let doc = crate::lexicon::bundled(PAGE).expect("schemas/place.hud.page.json is bundled");
    let lexicons = Lexicons::new([(*doc).clone()]);
    (doc, lexicons)
});

/// The most pages an app file has.
pub(crate) const PAGES: usize = 64;

/// What is wrong with an app file's `pages`, its own pages: a list of at
/// most `PAGES`, each what its lexicon (`place.hud.page`) describes, with
/// no key it does not name; its `path` a plain path (`plain_path`) that no
/// other page, no tab's `path` and no route's (`shadowed`) is; its
/// `markdown` a `.md` file's path within the app file's directory,
/// relative, never climbing out (`..`). Whether the file is there is
/// `pages_of`'s to say.
fn pages_problems(pages: &Value, tabs: &[Value], routes: &[Value], out: &mut Vec<String>) {
    let Some(pages) = pages.as_array().filter(|p| p.len() <= PAGES) else {
        out.push(format!(
            "app.pages: must be a list of at most {PAGES} pages"
        ));
        return;
    };
    let (doc, lexicons) = &*PAGE_LEXICON;
    let mut paths = Vec::new();
    for (i, page) in pages.iter().enumerate() {
        let at = format!("app.pages[{i}]");
        unknown(&doc["defs"], "main", page, &at, out);
        if let Err(e) = lexicons.validate(PAGE, page) {
            let rest = e.path.strip_prefix("object").unwrap_or(&e.path);
            out.push(format!("{at}{rest} {}", e.message));
            continue;
        }
        let path = page["path"].as_str().unwrap_or_default();
        let tab = tabs.iter().any(|t| t["path"] == path);
        if !plain_path(path) {
            out.push(format!(
                "{at}.path: must be a plain path, /segments of a-z, 0-9, - _ and ., no query or token"
            ));
        } else if paths.contains(&path) {
            out.push(format!("{at}.path: another page's too"));
        } else if tab || shadowed(path, routes) {
            out.push(format!("{at}.path: a tab's or a route's too"));
        }
        paths.push(path);
        let file = page["markdown"].as_str().unwrap_or_default();
        let within = !file.starts_with('/') && !file.split(['/', '\\']).any(|s| s == "..");
        if !within || !file.ends_with(".md") {
            out.push(format!(
                "{at}.markdown: must be a .md file's path within the app file's directory"
            ));
        }
    }
}

/// Whether `path` is a plain path: `/` and segments of lower-case ASCII
/// letters, digits, `-`, `_` and `.`, none empty, `.` or `..`.
fn plain_path(path: &str) -> bool {
    let ok = |b: u8| b.is_ascii_lowercase() || b.is_ascii_digit() || b"-_.".contains(&b);
    path.strip_prefix('/').is_some_and(|rest| {
        rest.split('/')
            .all(|s| !s.trim_matches('.').is_empty() && s.bytes().all(ok))
    })
}

/// Whether a route among `routes` has the plain path `path`, its tokens
/// any segment, its query string aside.
fn shadowed(path: &str, routes: &[Value]) -> bool {
    let want: Vec<&str> = path.split('/').collect();
    let route = |r: &str| {
        let have: Vec<&str> = r.split('?').next().unwrap_or_default().split('/').collect();
        have.len() == want.len()
            && have
                .iter()
                .zip(&want)
                .all(|(h, w)| h == w || (h.starts_with('{') && h.ends_with('}')))
    };
    routes.iter().filter_map(|r| r["path"].as_str()).any(route)
}

/// The pages of the app file `doc` of `domain`, checked by
/// `pages_problems`, each read from its Markdown's file in `dir`, the app
/// file's own, into blocks (`ui::page_blocks`); or why a file can't be
/// read, naming it.
fn pages_of(doc: &Value, domain: &str, dir: &Path) -> Result<Vec<view::Page>, String> {
    let pages = doc["pages"]
        .as_array()
        .map(Vec::as_slice)
        .unwrap_or_default();
    let app = doc["name"].as_str().unwrap_or_default();
    let mut out = Vec::new();
    for (i, p) in pages.iter().enumerate() {
        let text = |k: &str| p[k].as_str().unwrap_or_default().to_string();
        let found = read(&dir.join(text("markdown")));
        let markdown = found.map_err(|e| format!("app.pages[{i}].markdown: {e}"))?;
        out.push(view::Page {
            domain: domain.to_string(),
            app: app.to_string(),
            path: text("path"),
            title: text("title"),
            description: p["description"].as_str().map(str::to_string),
            blocks: crate::ui::page_blocks(&markdown, domain),
            markdown,
        });
    }
    Ok(out)
}

/// The frame's lexicon.
const FRAME: &str = "place.hud.frame";

/// The frame's lexicon document, and its validator.
static FRAME_LEXICON: LazyLock<(Arc<Value>, Lexicons)> = LazyLock::new(|| {
    let doc = crate::lexicon::bundled(FRAME).expect("schemas/place.hud.frame.json is bundled");
    let lexicons = Lexicons::new([(*doc).clone()]);
    (doc, lexicons)
});

/// What is wrong with an app file's `frame`: how its clients' shells draw
/// the app around its screens. It must be what its lexicon
/// (`place.hud.frame`) describes, with no key it does not name at any
/// level; then `destinations`, if any, `tabs`; each call drawn by a view
/// among `views` (the account's picture's a query, as a badge's is: it is
/// data); the picture's `tab` one of the tabs' `labels` and its `at`,
/// `name` and `handle` dotted paths (the last two, where given, the
/// account's name and handle in the same answer, for its accounts' rows);
/// each icon one of `catalog::FRAME_ICONS`; each of the
/// account's items a screen (a label, an icon and a call) or one the host
/// draws (`host`, signOut or signIn, at most one of each, `about` signIn's
/// alone); each link's `href` a path or an https URL; `sizes.wide` no
/// narrower than `sizes.content`, and `bands.sidebar` wider than
/// `bands.rail`, either left out its lexicon's default.
fn frame_problems(frame: &Value, labels: &[&str], views: &Views, out: &mut Vec<String>) {
    let (doc, lexicons) = &*FRAME_LEXICON;
    let defs = &doc["defs"];
    unknown(defs, "main", frame, "app.frame", out);
    if let Err(e) = lexicons.validate(FRAME, frame) {
        let rest = e.path.strip_prefix("object").unwrap_or(&e.path);
        out.push(format!("app.frame{rest} {}", e.message));
        return;
    }
    if frame.get("destinations").is_some_and(|d| d != "tabs") {
        out.push("app.frame.destinations: must be \"tabs\", the app's tabs".into());
    }
    if let Some(action) = frame.get("action") {
        icon(&action["icon"], "app.frame.action.icon", out);
        drawn(&action["call"], "app.frame.action.call", views, out);
    }
    let account = &frame["account"];
    if let Some(picture) = account.get("picture") {
        let at = "app.frame.account.picture";
        if !picture["tab"].as_str().is_some_and(|t| labels.contains(&t)) {
            out.push(format!("{at}.tab: must be a tab's label"));
        }
        let call = &picture["call"];
        let method = call["args"]["method"].as_str().unwrap_or_default();
        if call["name"] != "query" || !atproto::syntax::is_nsid(method) {
            out.push(format!("{at}.call: must be a query of a method's NSID"));
        }
        for key in ["at", "name", "handle"] {
            let path = picture.get(key).map_or(Some("given"), Value::as_str);
            if path.unwrap_or_default().split('.').any(str::is_empty) {
                out.push(format!(
                    "{at}.{key}: must be a dotted path, no segment empty"
                ));
            }
        }
    }
    let items = account["items"].as_array().map(Vec::as_slice);
    let mut hosts = Vec::new();
    for (i, item) in items.unwrap_or_default().iter().enumerate() {
        let at = format!("app.frame.account.items[{i}]");
        icon(&item["icon"], &format!("{at}.icon"), out);
        match (item.get("call"), item["host"].as_str()) {
            (Some(call), None) => {
                for k in ["label", "icon"]
                    .into_iter()
                    .filter(|k| item.get(k).is_none())
                {
                    out.push(format!("{at}.{k}: required with a call"));
                }
                drawn(call, &format!("{at}.call"), views, out);
            }
            (None, Some(host @ ("signOut" | "signIn"))) if hosts.contains(&host) => {
                out.push(format!("{at}.host: at most one {host} item"));
            }
            (None, Some(host @ ("signOut" | "signIn"))) => hosts.push(host),
            (None, Some(_)) => out.push(format!("{at}.host: must be signOut or signIn")),
            (Some(_), Some(_)) => out.push(format!("{at}: takes a call or a host, not both")),
            (None, None) => out.push(format!("{at}: needs a call or a host")),
        }
        if item.get("about").is_some() && item["host"] != "signIn" {
            out.push(format!("{at}.about: a signIn item's alone"));
        }
    }
    let links = frame["links"].as_array().map(Vec::as_slice);
    for (i, link) in links.unwrap_or_default().iter().enumerate() {
        if !linkable(link["href"].as_str().unwrap_or_default()) {
            out.push(format!(
                "app.frame.links[{i}].href: must be a path starting with / or an https URL"
            ));
        }
    }
    if let Some(aside) = frame.get("aside") {
        drawn(&aside["call"], "app.frame.aside.call", views, out);
    }
    let size = |def: &str, k: &str| {
        let given = frame[def][k].as_i64();
        given.or(defs[def]["properties"][k]["default"].as_i64())
    };
    let (content, wide) = (size("sizes", "content"), size("sizes", "wide"));
    if wide < content {
        out.push(format!(
            "app.frame.sizes.wide: must be no narrower than content ({})",
            content.unwrap_or_default()
        ));
    }
    let (rail, sidebar) = (size("bands", "rail"), size("bands", "sidebar"));
    if sidebar <= rail {
        out.push(format!(
            "app.frame.bands.sidebar: must be wider than rail ({})",
            rail.unwrap_or_default()
        ));
    }
}

/// Whether `href` is a path of the app's own site (starting with `/`, not
/// `//`) or an https URL: where a link of an app file's may go.
fn linkable(href: &str) -> bool {
    let https = url::Url::parse(href).is_ok_and(|u| u.scheme() == "https" && u.host().is_some());
    let path = href.starts_with('/') && !href.starts_with("//");
    path || https
}

/// The sign-in screen's lexicon.
const SIGN_IN: &str = "place.hud.signIn";

/// The sign-in screen's lexicon document, and its validator.
static SIGN_IN_LEXICON: LazyLock<(Arc<Value>, Lexicons)> = LazyLock::new(|| {
    let doc = crate::lexicon::bundled(SIGN_IN).expect("schemas/place.hud.signIn.json is bundled");
    let lexicons = Lexicons::new([(*doc).clone()]);
    (doc, lexicons)
});

/// The hrefs of the Markdown links (`[label](href)`) in `text`.
fn hrefs(text: &str) -> impl Iterator<Item = &str> {
    let after = text.split("](").skip(1);
    after.map(|rest| rest.split(')').next().unwrap_or_default())
}

/// What is wrong with an app file's `signIn`: what its clients' own
/// sign-in screen says, and where it finds accounts as a handle is typed.
/// It must be what its lexicon (`place.hud.signIn`) describes, with no key
/// it does not name at any level; each link in its `text` and `legal`
/// (`[label](href)`) a path or an https URL; its typeahead's `url` an
/// https origin (no path, query or fragment), its `params` an object of
/// strings, numbers and booleans, and its paths dotted, no segment empty.
fn sign_in_problems(sign_in: &Value, out: &mut Vec<String>) {
    let (doc, lexicons) = &*SIGN_IN_LEXICON;
    unknown(&doc["defs"], "main", sign_in, "app.signIn", out);
    if let Err(e) = lexicons.validate(SIGN_IN, sign_in) {
        let rest = e.path.strip_prefix("object").unwrap_or(&e.path);
        out.push(format!("app.signIn{rest} {}", e.message));
        return;
    }
    for key in ["text", "legal"] {
        let text = sign_in[key].as_str().unwrap_or_default();
        if !hrefs(text).all(linkable) {
            out.push(format!(
                "app.signIn.{key}: each link must go to a path starting with / or an https URL"
            ));
        }
    }
    let Some(typeahead) = sign_in.get("typeahead") else {
        return;
    };
    let at = "app.signIn.typeahead";
    let url = url::Url::parse(typeahead["url"].as_str().unwrap_or_default());
    let origin = url.is_ok_and(|u| {
        let bare = u.path() == "/" && u.query().is_none() && u.fragment().is_none();
        u.scheme() == "https" && u.host().is_some() && u.username().is_empty() && bare
    });
    if !origin {
        out.push(format!(
            "{at}.url: must be an https origin, as https://typeahead.waow.tech"
        ));
    }
    let scalar = |v: &Value| v.is_string() || v.is_number() || v.is_boolean();
    let params = typeahead.get("params").map(Value::as_object);
    if params.is_some_and(|p| !p.is_some_and(|p| p.values().all(scalar))) {
        out.push(format!(
            "{at}.params: must be an object of strings, numbers and booleans"
        ));
    }
    for key in ["items", "did", "handle", "name", "avatar", "avatarFallback"] {
        let path = typeahead.get(key).map_or(Some("given"), Value::as_str);
        if path.unwrap_or_default().split('.').any(str::is_empty) {
            out.push(format!(
                "{at}.{key}: must be a dotted path, no segment empty"
            ));
        }
    }
}

/// Add to `out` the keys of `value` that the def `def` among the frame's
/// lexicon's `defs` does not name, and those of the objects it holds,
/// wherever they are, `at` saying where.
fn unknown(defs: &Value, def: &str, value: &Value, at: &str, out: &mut Vec<String>) {
    let Some(o) = value.as_object() else {
        return;
    };
    for (k, v) in o {
        let p = &defs[def]["properties"][k.as_str()];
        let of = p["ref"].as_str().or(p["items"]["ref"].as_str());
        let of = of.map(|r| r.trim_start_matches('#'));
        match (p["type"].as_str(), of) {
            (None, _) => out.push(format!("{at}: unknown key \"{k}\"")),
            (Some("ref"), Some(r)) => unknown(defs, r, v, &format!("{at}.{k}"), out),
            (Some("array"), Some(r)) => {
                let each = v.as_array().map(Vec::as_slice).unwrap_or_default();
                for (i, e) in each.iter().enumerate() {
                    unknown(defs, r, e, &format!("{at}.{k}[{i}]"), out);
                }
            }
            _ => {}
        }
    }
}

/// Add to `out`, at `at`, that `v` is an icon no shell draws: none of
/// `catalog::FRAME_ICONS`.
fn icon(v: &Value, at: &str, out: &mut Vec<String>) {
    if v.as_str().is_some_and(|i| !FRAME_ICONS.contains(&i)) {
        out.push(format!("{at}: must be one of catalog::FRAME_ICONS"));
    }
}

/// What an app file's `head` may say.
pub(crate) const HEAD: [&str; 6] = [
    "siteName",
    "title",
    "description",
    "image",
    "imageAlt",
    "twitter",
];

/// The most characters a text of an app file's `head` takes.
pub(crate) const HEAD_TEXT: usize = 300;

/// What is wrong with an app file's `head`: what a page of the app says in
/// its HTML head where its view's head (`_meta.ui.head`) says nothing. Its
/// site's name (`siteName`, required), the title and description of a page
/// with none, each text of 1 to 300 characters; a picture, an absolute
/// https URL, and its alt text; its X account (`twitter`), as `@name`.
fn head_problems(head: &Value, out: &mut Vec<String>) {
    let Some(o) = head.as_object() else {
        out.push("app.head: must be an object".into());
        return;
    };
    for k in o.keys().filter(|k| !HEAD.contains(&k.as_str())) {
        out.push(format!("app.head: unknown key \"{k}\""));
    }
    if !o.contains_key("siteName") {
        out.push("app.head.siteName: required".into());
    }
    let text = |v: &Value| {
        v.as_str()
            .is_some_and(|s| !s.trim().is_empty() && s.chars().count() <= HEAD_TEXT)
    };
    for k in ["siteName", "title", "description", "imageAlt"] {
        if o.get(k).is_some_and(|v| !text(v)) {
            out.push(format!(
                "app.head.{k}: must be text of 1 to {HEAD_TEXT} characters"
            ));
        }
    }
    let https = |v: &Value| {
        v.as_str()
            .and_then(|s| url::Url::parse(s).ok())
            .is_some_and(|u| u.scheme() == "https" && u.host().is_some())
    };
    if o.get("image").is_some_and(|v| !https(v)) {
        out.push("app.head.image: must be an https URL".into());
    }
    let account = |v: &Value| {
        v.as_str()
            .and_then(|s| s.strip_prefix('@'))
            .is_some_and(|n| {
                (1..=15).contains(&n.len())
                    && n.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'_')
            })
    };
    if o.get("twitter").is_some_and(|v| !account(v)) {
        out.push("app.head.twitter: must be an account, as @name".into());
    }
}

/// The procedure call an app file's `push.register` or `push.unregister`
/// is: its method, its service and its input, a template of
/// `PUSH_BINDINGS`.
fn call_of(c: &Value) -> view::Call {
    let text = |k: &str| c[k].as_str().unwrap_or_default().to_string();
    view::Call {
        method: text("method"),
        service: text("service"),
        input: c["input"].clone(),
        deletes: false,
    }
}

/// The calls an app file, checked, makes for push: its `register` and
/// `unregister`; none where it declares no push.
fn push_calls(doc: &Value) -> Vec<view::Call> {
    let push = &doc["push"];
    ["register", "unregister"]
        .into_iter()
        .filter(|k| push[k].is_object())
        .map(|k| call_of(&push[k]))
        .collect()
}

/// An app file's `refresh`, checked, called after a write of one of
/// `collections`; none where it names none.
fn refresh_of(doc: &Value, collections: &BTreeSet<String>) -> Option<view::Refresh> {
    let r = doc.get("refresh")?;
    Some(view::Refresh {
        method: r["method"].as_str().unwrap_or_default().to_string(),
        service: r["service"].as_str().unwrap_or_default().to_string(),
        collections: collections.clone(),
    })
}

/// Add to `out` what is wrong with an app file's `refresh`: an object
/// naming a procedure's `method` and the `service` it is of, and nothing
/// else. HUD sends it `{"uris": [...]}`, the records just
/// written, so it needs no lexicon bundled.
fn refresh_problems(refresh: &Value, out: &mut Vec<String>) {
    let Some(o) = refresh.as_object() else {
        out.push("app.refresh: must be an object, a procedure's method and service".into());
        return;
    };
    let method = o.get("method").and_then(Value::as_str).unwrap_or_default();
    if !atproto::syntax::is_nsid(method) {
        out.push("app.refresh.method: must be a method's NSID".into());
    }
    let service = o.get("service").and_then(Value::as_str).unwrap_or_default();
    if let Err(why) = crate::xrpc::Service::parse(service) {
        out.push(format!("app.refresh.service: {why}"));
    }
    for k in o
        .keys()
        .filter(|k| !["method", "service"].contains(&k.as_str()))
    {
        out.push(format!("app.refresh.{k}: not a field of it"));
    }
}

/// The most permission sets an app file names.
pub(crate) const SETS: usize = 8;

/// The permission sets an app file, checked, names: what sign-in asks for
/// first (`scope::including`); none where it names none.
fn sets_of(doc: &Value) -> Vec<Include> {
    let named = doc["permissions"].as_array().map_or(&[][..], Vec::as_slice);
    let set = |p: &Value| Include {
        nsid: p["include"].as_str().unwrap_or_default().to_string(),
        service: p["service"].as_str().map(str::to_string),
    };
    named.iter().map(set).collect()
}

/// Add to `out` what is wrong with an app file's `permissions`: a list of
/// 1 to `SETS` permission sets, each an object naming the set's NSID
/// (`include`) and, where its methods are called at a service, that
/// service (`service`), whose audience its `rpc` permissions inherit; and
/// nothing else. What each grants is the set's to say, as the account's
/// server resolves it: checked against the views as HUD starts
/// (`Hud::sets_ungranted`).
fn permissions_problems(permissions: &Value, out: &mut Vec<String>) {
    let named = permissions.as_array();
    let Some(named) = named.filter(|n| (1..=SETS).contains(&n.len())) else {
        out.push(format!(
            "app.permissions: must be a list of 1 to {SETS} permission sets"
        ));
        return;
    };
    for (i, p) in named.iter().enumerate() {
        let at = format!("app.permissions[{i}]");
        let Some(o) = p.as_object() else {
            out.push(format!(
                "{at}: must be an object, a set's include and service"
            ));
            continue;
        };
        let nsid = o.get("include").and_then(Value::as_str);
        if !nsid.is_some_and(atproto::syntax::is_nsid) {
            out.push(format!("{at}.include: must be a permission set's NSID"));
        }
        if let Some(s) = o.get("service")
            && let Err(why) = crate::xrpc::Service::parse(s.as_str().unwrap_or_default())
        {
            out.push(format!("{at}.service: {why}"));
        }
        for k in o
            .keys()
            .filter(|k| !["include", "service"].contains(&k.as_str()))
        {
            out.push(format!("{at}.{k}: not a field of it"));
        }
    }
}

/// Add to `out` what is wrong with an app file's `push`: `register` and
/// `unregister` each a procedure HUD has a lexicon of (an app's own or a
/// bundled one, `Views::lexicon_docs`), of a service,
/// its input what the lexicon takes and requires, binding the device's
/// token and nothing but `PUSH_BINDINGS`; and `open`, if any, a list of
/// what a tapped notification opens, each `when` (the payload's fields, as
/// patterns of `{token}`s) and the `path` of one of the app's `routes`
/// those tokens fill.
fn push_problems(push: &Value, routes: &[Value], views: &Views, out: &mut Vec<String>) {
    let Some(o) = push.as_object() else {
        out.push("app.push: must be an object".into());
        return;
    };
    let lexicons = views.lexicon_docs();
    for k in ["register", "unregister"] {
        let at = format!("app.push.{k}");
        let Some(c) = o.get(k).filter(|c| c.is_object()) else {
            out.push(format!(
                "{at}: required, a procedure's method, service and input"
            ));
            continue;
        };
        let call = call_of(c);
        if !atproto::syntax::is_nsid(&call.method) {
            out.push(format!("{at}.method: must be a method's NSID"));
            continue;
        }
        if let Err(why) = crate::xrpc::Service::parse(&call.service) {
            out.push(format!("{at}.service: {why}"));
        }
        let problems = view::call_problems(&call, &lexicons);
        out.extend(problems.into_iter().map(|p| format!("{at}: {p}")));
        let mut bound = Vec::new();
        bindings(&call.input, &format!("{at}.input"), &mut bound, out);
        if !bound.contains(&"$token") {
            out.push(format!(
                "{at}.input: must hold the device's token, {{\"$token\": true}}"
            ));
        }
    }
    let open = match o.get("open") {
        None => &[][..],
        Some(Value::Array(open)) => open.as_slice(),
        Some(_) => {
            out.push("app.push.open: must be a list of what a notification opens".into());
            &[]
        }
    };
    for (i, e) in open.iter().enumerate() {
        opening_problems(e, &format!("app.push.open[{i}]"), routes, out);
    }
}

/// Add to `out` the bindings of an input template that are no
/// `PUSH_BINDINGS`, and to `bound` those that are.
fn bindings(v: &Value, at: &str, bound: &mut Vec<&'static str>, out: &mut Vec<String>) {
    match v {
        Value::Object(o) => {
            for (k, x) in o.iter().filter(|(k, _)| k.starts_with('$')) {
                match PUSH_BINDINGS.into_iter().find(|b| b == k) {
                    Some(b) if o.len() == 1 && *x == Value::Bool(true) => bound.push(b),
                    _ => out.push(format!(
                        "{at}: {k} is no binding of a push call, which binds {{\"$token\": true}}, {{\"$appId\": true}} and {{\"$platform\": true}}"
                    )),
                }
            }
            for (k, x) in o.iter().filter(|(k, _)| !k.starts_with('$')) {
                bindings(x, &format!("{at}.{k}"), bound, out);
            }
        }
        Value::Array(a) => {
            for (i, x) in a.iter().enumerate() {
                bindings(x, &format!("{at}[{i}]"), bound, out);
            }
        }
        _ => {}
    }
}

/// The `{token}`s a pattern names, as routes write them (`{actor}`,
/// `{actor:did}`), by name.
fn tokens(pattern: &str) -> Vec<&str> {
    pattern
        .split('{')
        .skip(1)
        .filter_map(|piece| piece.split_once('}'))
        .map(|(token, _)| token.split(':').next().unwrap_or_default())
        .collect()
}

/// Add to `out` what is wrong with route `r`'s `pager` and `under`, at
/// `at`: `pager` is true where its screen is a story, opened as the one
/// page of the clients' stories pager over where it is opened from; its
/// `under`, a route's path whose tokens its own path binds, is the screen
/// under it where its URL is loaded (a story's account's profile).
fn pager_problems(r: &Value, at: &str, routes: &[Value], out: &mut Vec<String>) {
    if !r["pager"].is_null() && r["pager"] != true {
        out.push(format!("{at}.pager: must be true"));
    }
    let Some(under) = r.get("under") else {
        return;
    };
    let Some(path) = under.as_str().filter(|p| p.starts_with('/')) else {
        return out.push(format!("{at}.under: must be a path, starting with /"));
    };
    if r["pager"] != true {
        out.push(format!("{at}.under: only a pager's route has one"));
    }
    let own = tokens(r["path"].as_str().unwrap_or_default());
    for t in tokens(path).into_iter().filter(|t| !own.contains(t)) {
        out.push(format!("{at}.under: {{{t}}} is in no token of its path"));
    }
    if !routed(path, routes) {
        out.push(format!("{at}.under: no route's path is {path}"));
    }
}

/// Whether the path `open` (its tokens any segment) is the path of a
/// route among `routes`, segment by segment, their query strings aside.
fn routed(open: &str, routes: &[Value]) -> bool {
    let segments = |p: &str| -> Vec<String> {
        let path = p.split('?').next().unwrap_or_default();
        path.split('/').map(str::to_string).collect()
    };
    let token = |s: &str| s.starts_with('{') && s.ends_with('}');
    let want = segments(open);
    routes.iter().filter_map(|r| r["path"].as_str()).any(|r| {
        let have = segments(r);
        have.len() == want.len()
            && have
                .iter()
                .zip(&want)
                .all(|(h, w)| h == w || (token(h) && token(w)))
    })
}

/// Add to `out` what is wrong with one of `push.open`, at `at`: `when`, an
/// object of one or more of the payload's fields, each a pattern; and
/// `path`, a route's path whose tokens `when` binds.
fn opening_problems(e: &Value, at: &str, routes: &[Value], out: &mut Vec<String>) {
    let when = e["when"].as_object();
    let patterns: Vec<&str> = when
        .into_iter()
        .flatten()
        .filter_map(|(_, p)| p.as_str())
        .collect();
    if !when.is_some_and(|w| !w.is_empty() && w.len() == patterns.len()) {
        out.push(format!(
            "{at}.when: must be an object of the notification's fields, each a pattern"
        ));
    }
    let Some(path) = e["path"].as_str().filter(|p| p.starts_with('/')) else {
        out.push(format!("{at}.path: must be a path, starting with /"));
        return;
    };
    let bound: Vec<&str> = patterns.iter().flat_map(|p| tokens(p)).collect();
    for t in tokens(path).into_iter().filter(|t| !bound.contains(t)) {
        out.push(format!("{at}.path: {{{t}}} is in no pattern of when"));
    }
    if !routed(path, routes) {
        out.push(format!("{at}.path: no route's path is {path}"));
    }
}

/// Add to `out` what is wrong with the tool call `call`, at `at`: it must
/// draw what a view among `views` draws, as a query of a method view's
/// method, an app's page (`describe_app`), or a record (`get_record`, by
/// its at-uri) or records (`list_records`) of a collection a view draws.
fn drawn(call: &Value, at: &str, views: &Views, out: &mut Vec<String>) {
    let args = &call["args"];
    let text = |k: &str| args[k].as_str().unwrap_or_default();
    let all = views.all().iter().map(|b| &b.view);
    let (what, found) = match call["name"].as_str() {
        Some("query") => {
            let m = text("method");
            (m, all.clone().any(|v| v.method.as_deref() == Some(m)))
        }
        Some("describe_app") => {
            let d = text("domain");
            let page = |v: &view::View| v.page.is_some() && v.domain.as_deref() == Some(d);
            (d, all.clone().any(page))
        }
        Some("get_record") => {
            let c = text("uri").split('/').nth(3).unwrap_or_default();
            let routed = |v: &view::View| v.records.iter().any(|r| r.collection == c);
            let found = all
                .clone()
                .any(|v| v.collection.as_deref() == Some(c) || routed(v));
            (c, found)
        }
        Some("list_records") => {
            let c = text("collection");
            (c, all.clone().any(|v| v.collection.as_deref() == Some(c)))
        }
        _ => {
            out.push(format!(
                "{at}: must be a call of query, describe_app, get_record or list_records"
            ));
            return;
        }
    };
    if !found {
        out.push(format!("{at}: no view draws {what:?}"));
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use serde_json::json;

    /// A new empty directory of this test's own.
    fn temp_dir(name: &str) -> PathBuf {
        let dir = std::env::temp_dir().join(format!("hud-operator-{name}-{}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(dir.join("views")).unwrap();
        dir
    }

    /// `dir` with `files` written in it, by their paths within it.
    fn write(dir: &Path, files: &[(&str, Value)]) {
        for (path, doc) in files {
            std::fs::write(dir.join(path), doc.to_string()).unwrap();
        }
    }

    /// A method view of `method`, at Bluesky's AppView, calling `call`.
    fn method_view(method: &str, call: &str) -> Value {
        json!({ "method": method, "service": "did:web:api.bsky.app#bsky_appview",
                "description": "Lists",
                "query": { "items": "lists", "layout": { "component": "Action", "props": {
                    "label": "Mute", "done": "Muted",
                    "call": { "method": call, "service": "did:web:api.bsky.app#bsky_appview",
                              "input": { "actor": { "$": "did" } } } } } } })
    }

    /// An app of `example.test`: a tab and a route, each a query.
    fn app(method: &str) -> Value {
        json!({ "domain": "example.test", "name": "Example",
                "tabs": [{ "label": "Lists", "icon": "feed",
                           "call": { "name": "query", "args": { "method": method } },
                           "guest": "call" }],
                "routes": [{ "path": "/lists/{actor}", "tab": "Lists",
                             "call": { "name": "query", "args": { "method": method,
                                                                  "params": { "actor": "{actor}" } } } }] })
    }

    /// A directory with a valid app and its view loads, its view trusted:
    /// its call is one the server sends, and no bundled view's is.
    #[test]
    fn an_app_and_its_view_load() {
        let dir = temp_dir("valid");
        write(
            &dir,
            &[
                ("example.test.json", app("app.bsky.graph.getLists")),
                ("package.json", json!({ "name": "a client" })),
                (
                    "views/example-lists.json",
                    method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"),
                ),
            ],
        );
        let loaded = load(&dir, true).unwrap();
        assert_eq!(loaded.apps, ["example.test"]);
        assert_eq!(loaded.ids, ["example-lists"]);
        let b = loaded
            .views
            .all()
            .iter()
            .find(|b| b.id == "example-lists")
            .unwrap();
        assert_eq!(
            b.file,
            dir.join("views/example-lists.json").display().to_string()
        );
        let mute = (
            "social.grain.graph.muteActor",
            "did:web:api.bsky.app#bsky_appview",
        );
        assert!(loaded.views.calls(mute.0, mute.1));
        assert!(!Views::built_in().calls(mute.0, mute.1));
        assert_eq!(
            loaded.views.service("app.bsky.graph.getLists"),
            Some(mute.1)
        );
        // The bundled views are all there besides.
        assert_eq!(loaded.views.all().len(), Views::built_in().all().len() + 1);
        // Views alone, with no app, load too.
        std::fs::remove_file(dir.join("example.test.json")).unwrap();
        assert_eq!(load(&dir, true).unwrap().apps, Vec::<String>::new());
    }

    /// An operator's view replaces the bundled view of its id, and any
    /// drawing what it draws.
    #[test]
    fn the_operators_view_wins() {
        let built = Views::built_in();
        let bundled = built.all().iter().find(|b| b.id == "bsky-feed").unwrap();
        let method = bundled.view.method.clone().unwrap();
        let dir = temp_dir("wins");
        let mut mine = method_view(&method, "social.grain.graph.muteActor");
        mine["description"] = json!("The operator's feed");
        write(&dir, &[("views/bsky-feed.json", mine.clone())]);
        let loaded = load(&dir, true).unwrap();
        let of = |views: &Views| {
            let found = views
                .all()
                .iter()
                .filter(|b| b.view.method.as_deref() == Some(&method));
            found
                .map(|b| (b.id.clone(), b.view.description.clone()))
                .collect::<Vec<_>>()
        };
        assert_eq!(
            of(&loaded.views),
            [("bsky-feed".to_string(), "The operator's feed".to_string())]
        );
        // Under another id, it replaces the view drawing its method.
        let dir = temp_dir("wins-drawn");
        write(&dir, &[("views/mine.json", mine)]);
        let loaded = load(&dir, true).unwrap();
        assert_eq!(
            of(&loaded.views),
            [("mine".to_string(), "The operator's feed".to_string())]
        );
        assert!(!loaded.views.all().iter().any(|b| b.id == "bsky-feed"));
    }

    /// What refuses startup, each naming its file.
    #[test]
    fn refusals_name_their_file() {
        let refused = |name: &str, files: &[(&str, Value)]| {
            let dir = temp_dir(name);
            write(&dir, files);
            (dir.clone(), load(&dir, true).unwrap_err().join("\n"))
        };
        let lists = || method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor");
        // A call to what is no procedure.
        let (dir, err) = refused(
            "query-call",
            &[(
                "views/v.json",
                method_view("app.bsky.graph.getLists", "app.bsky.graph.getList"),
            )],
        );
        let file = dir.join("views/v.json").display().to_string();
        assert_eq!(
            err,
            format!("{file}: app.bsky.graph.getList is a query, not a procedure")
        );
        // A broken view.
        let (dir, err) = refused("broken", &[("views/v.json", json!({ "method": "a.b.c" }))]);
        assert!(
            err.starts_with(&format!("{}: ", dir.join("views/v.json").display())),
            "{err}"
        );
        // A view that is not JSON, or not text.
        let dir = temp_dir("not-json");
        std::fs::write(dir.join("views/v.json"), "{").unwrap();
        assert!(
            load(&dir, true).unwrap_err()[0]
                .starts_with(&format!("{}: EOF", dir.join("views/v.json").display()))
        );
        std::fs::write(dir.join("views/v.json"), [0xff, 0xfe]).unwrap();
        assert!(
            load(&dir, true).unwrap_err()[0]
                .starts_with(&format!("{}: ", dir.join("views/v.json").display()))
        );
        // A route naming a method no view draws.
        let mut bad = app("app.bsky.graph.getLists");
        bad["routes"][0]["call"]["args"]["method"] = json!("app.bsky.graph.getStarterPacks");
        let (dir, err) = refused(
            "route",
            &[("example.test.json", bad), ("views/v.json", lists())],
        );
        assert_eq!(
            err,
            format!(
                "{}: app.routes[0].call: no view draws \"app.bsky.graph.getStarterPacks\"",
                dir.join("example.test.json").display()
            )
        );
        // An app file that is not JSON, or not text.
        let dir = temp_dir("app-json");
        let path = dir.join("example.test.json");
        std::fs::write(&path, "[").unwrap();
        assert!(load(&dir, true).unwrap_err()[0].starts_with(&format!("{}: EOF", path.display())));
        std::fs::write(&path, [0xff, 0xfe]).unwrap();
        assert!(load(&dir, true).unwrap_err()[0].starts_with(&format!("{}: ", path.display())));
        // A view drawing a collection a bundled view draws as its query.
        let mut posts = json!({ "collection": "app.bsky.feed.post", "description": "Posts",
                                "list": { "layout": { "component": "Badge", "props": { "value": "x" } } },
                                "record": { "layout": { "component": "Badge", "props": { "value": "x" } } } });
        let (dir, err) = refused("conflict", &[("views/posts.json", posts.clone())]);
        let thread = Views::built_in()
            .all()
            .iter()
            .find(|b| {
                b.view
                    .records
                    .iter()
                    .any(|r| r.collection == "app.bsky.feed.post")
            })
            .unwrap()
            .file
            .clone();
        assert_eq!(
            err,
            format!(
                "{thread}: {} draws app.bsky.feed.post as records",
                dir.join("views/posts.json").display()
            )
        );
        // A trusted collection view draws both modes.
        posts["collection"] = json!("example.test.thing");
        posts.as_object_mut().unwrap().remove("record");
        let (dir, err) = refused("one-mode", &[("views/thing.json", posts)]);
        assert_eq!(
            err,
            format!(
                "{}: view: a trusted collection view draws a page of records (list) and one (record)",
                dir.join("views/thing.json").display()
            )
        );
        // No such directory, or nothing in it.
        let gone = std::env::temp_dir().join("hud-operator-none-such");
        assert!(load(&gone, true).unwrap_err()[0].starts_with(&format!("{}: ", gone.display())));
        let dir = temp_dir("empty");
        assert_eq!(
            load(&dir, true).unwrap_err(),
            [format!(
                "{}: no app (<domain>.json) and no view (views/<id>.json)",
                dir.display()
            )]
        );
    }

    /// What a view's deletes may reach (`collections`) is what sign-in asks
    /// to delete alone (`repo:<c>?action=delete`), but for a collection a
    /// view writes, which it asks to write, once.
    #[test]
    fn a_plans_collections_are_asked_to_delete() {
        let dir = temp_dir("plan-scope");
        let mut view = method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor");
        view["query"]["layout"] = json!({ "component": "Action", "props": {
            "label": "Delete all", "deletes": {
                "method": "social.grain.server.getAccountDeletionPlan",
                "service": "did:web:grain.social#grain_appview",
                "repeat": true, "collections": ["example.thing.one", "app.bsky.feed.like"] } } });
        write(&dir, &[("views/example-lists.json", view)]);
        let loaded = load(&dir, true).unwrap();
        let s = crate::scope::asked(&loaded.views, false, false);
        let tokens: Vec<&str> = s.split(' ').collect();
        assert!(
            tokens.contains(&"repo:example.thing.one?action=delete"),
            "{s}"
        );
        assert!(tokens.contains(&"repo:app.bsky.feed.like"), "{s}");
        assert!(!s.contains("app.bsky.feed.like?action=delete"), "{s}");
    }

    /// Grain's apps, as its repository serves them (`HUD_APPS`): its app
    /// file and its views load, each view's calls and query joins passing
    /// the checks against HUD's bundled lexicons, and the server sends
    /// their calls.
    #[test]
    fn grains_apps_load() {
        let loaded = load(Path::new(view::GRAIN_APPS), true).unwrap();
        assert_eq!(loaded.apps, ["grain.social"]);
        assert_eq!(loaded.ids.len(), 17);
        assert!(loaded.ids.iter().all(|id| id.starts_with("grain-")));
        let calls: Vec<&view::Call> = loaded
            .views
            .all()
            .iter()
            .filter(|b| loaded.ids.contains(&b.id))
            .flat_map(|b| &b.view.calls)
            .collect();
        assert!(!calls.is_empty());
        assert!(
            calls.iter().any(|c| c.deletes),
            "a gallery deleted as planned"
        );
        for c in calls {
            let sent = |v: &Views| match c.deletes {
                true => v.deletes(&c.method, &c.service),
                false => v.calls(&c.method, &c.service),
            };
            assert!(sent(&loaded.views), "{}", c.method);
            assert!(!sent(&Views::built_in()), "{}", c.method);
        }
        // Its app file registers a device for push, which the server sends
        // as it sends a view's calls.
        let grain = "did:web:grain.social#grain_appview";
        let pushes: Vec<&str> = loaded
            .views
            .pushes()
            .iter()
            .map(|c| c.method.as_str())
            .collect();
        assert_eq!(
            pushes,
            [
                "social.grain.notification.registerPush",
                "social.grain.notification.unregisterPush"
            ]
        );
        for m in pushes {
            assert!(loaded.views.calls(m, grain), "{m}");
            assert!(!Views::built_in().calls(m, grain), "{m}");
        }
        assert_eq!(loaded.views.with(Vec::new()).pushes().len(), 2);
        // Served alone, as an instance with no workspace serves them: its
        // views and pushes, and no bundled view.
        let alone = load(Path::new(view::GRAIN_APPS), false).unwrap();
        let ids: Vec<&str> = alone.views.all().iter().map(|b| b.id.as_str()).collect();
        assert_eq!(ids, loaded.ids);
        assert_eq!(alone.views.pushes(), loaded.views.pushes());
        // Its app file names its refresh, called after a write of what
        // its views write, whose service sign-in asks to call.
        let refreshes = loaded.views.refreshes();
        assert_eq!(refreshes.len(), 1);
        assert_eq!(refreshes[0].method, "social.grain.sync.indexRecords");
        assert_eq!(refreshes[0].service, grain);
        assert!(refreshes[0].collections.contains("social.grain.comment"));
        assert!(refreshes[0].collections.contains("social.grain.favorite"));
        assert!(
            refreshes[0]
                .collections
                .iter()
                .all(|c| c.starts_with("social.grain."))
        );
        assert_eq!(alone.views.refreshes(), refreshes);
        assert_eq!(loaded.views.with(Vec::new()).refreshes(), refreshes);
        assert!(loaded.views.called().contains(grain));
        assert!(Views::built_in().refreshes().is_empty());
        // Its app file draws its own sign-in screen: its web clients are sent
        // straight on to the account's server.
        assert_eq!(loaded.views.sign_ins(), ["grain.social"]);
        assert_eq!(alone.views.sign_ins(), ["grain.social"]);
        assert_eq!(loaded.views.with(Vec::new()).sign_ins(), ["grain.social"]);
        assert!(Views::built_in().sign_ins().is_empty());
        // Its app file names Grain's permission set, asked for first at
        // sign-in, its methods called at Grain's AppView.
        let set = Include {
            nsid: "social.grain.authFull".into(),
            service: Some(grain.into()),
        };
        let sets = std::slice::from_ref(&set);
        assert_eq!(loaded.views.sets(), sets);
        assert_eq!(alone.views.sets(), sets);
        assert_eq!(loaded.views.with(Vec::new()).sets(), sets);
        assert!(Views::built_in().sets().is_empty());
    }

    /// Grain's app file's own pages load, each read from its Markdown's
    /// file into blocks, its links to Grain's own paths opening them on
    /// grain.social; and an app file with none has none, as ever.
    #[test]
    fn grains_pages_load() {
        let loaded = load(Path::new(view::GRAIN_APPS), true).unwrap();
        let terms = loaded.views.page("grain.social", "/support/terms").unwrap();
        assert_eq!(terms.app, "Grain");
        assert_eq!(terms.title, "Terms and Conditions");
        assert!(terms.markdown.starts_with("*Last Updated: June 3, 2025*"));
        assert_eq!(
            terms.blocks[1],
            json!({ "kind": "heading", "level": 2, "runs": [{ "text": "Overview" }] })
        );
        let safety = loaded
            .views
            .page("grain.social", "/support/child-safety")
            .unwrap();
        let said = serde_json::to_string(&safety.blocks).unwrap();
        assert!(said.contains("\"link\":\"https://grain.social/support/terms\""));
        assert!(said.contains("\"link\":\"mailto:support@grain.social\""));
        assert!(loaded.views.page("grain.social", "/support/x").is_none());
        assert!(loaded.views.page("bsky.app", "/support/terms").is_none());
        // Kept as other views are added, and served alone too.
        let kept = loaded.views.with(Vec::new());
        assert_eq!(kept.page("grain.social", "/support/terms"), Some(terms));
        let alone = load(Path::new(view::GRAIN_APPS), false).unwrap();
        assert!(
            alone
                .views
                .page("grain.social", "/support/privacy")
                .is_some()
        );
        assert!(
            Views::built_in()
                .page("grain.social", "/support/terms")
                .is_none()
        );
        // An app file with no pages loads as it did, with none.
        let dir = temp_dir("pageless");
        write(
            &dir,
            &[
                ("example.test.json", app("app.bsky.graph.getLists")),
                (
                    "views/example-lists.json",
                    method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"),
                ),
            ],
        );
        let pageless = load(&dir, true).unwrap();
        assert!(pageless.views.page("example.test", "/about").is_none());
        // One with a page whose file is there loads it; one whose file is
        // not refuses startup, naming the app file and the page.
        let mut doc = app("app.bsky.graph.getLists");
        doc["pages"] =
            json!([{ "path": "/about", "title": "About", "markdown": "pages/about.md" }]);
        write(&dir, &[("example.test.json", doc)]);
        let err = load(&dir, true).unwrap_err().join("\n");
        let file = dir.join("example.test.json").display().to_string();
        let md = dir.join("pages/about.md").display().to_string();
        assert!(
            err.starts_with(&format!("{file}: app.pages[0].markdown: {md}: ")),
            "{err}"
        );
        std::fs::create_dir_all(dir.join("pages")).unwrap();
        std::fs::write(
            dir.join("pages/about.md"),
            "# About\n\nSee [terms](/terms).",
        )
        .unwrap();
        let about = load(&dir, true).unwrap();
        let page = about.views.page("example.test", "/about").unwrap();
        assert_eq!(page.description, None);
        assert_eq!(page.app, "Example");
        assert_eq!(
            page.blocks[1]["runs"][1],
            json!({ "text": "terms", "link": "https://example.test/terms" })
        );
    }

    /// An app file's `pages`: a list, each page what its lexicon says, at
    /// a plain path no other page, tab or route has, its Markdown a `.md`
    /// file's path within the app's directory.
    #[test]
    fn app_pages_checked() {
        let views = view::views();
        let text = std::fs::read_to_string(Path::new(view::GRAIN_APPS).join("grain.social.json"));
        let grain: Value = serde_json::from_str(&text.unwrap()).unwrap();
        let check = |pages: Value| {
            let mut doc = grain.clone();
            doc["pages"] = pages;
            app_problems(&doc, "grain.social", views)
        };
        assert!(check(grain["pages"].clone()).is_empty());
        let mut pageless = grain.clone();
        pageless.as_object_mut().unwrap().remove("pages");
        assert!(app_problems(&pageless, "grain.social", views).is_empty());
        let too_many = json!(vec![
            json!({ "path": "/a", "title": "A", "markdown": "a.md" });
            65
        ]);
        for pages in [json!({}), too_many] {
            assert_eq!(
                check(pages),
                ["app.pages: must be a list of at most 64 pages"]
            );
        }
        let page = |path: &str, markdown: &str| json!({ "path": path, "title": "A", "markdown": markdown });
        let problems = check(json!([
            { "path": "/a", "markdown": "a.md", "x": 1 },
            page("/A", "a.md"),
            page("/a/", "a.md"),
            page("/a?b=c", "a.md"),
            page("/{x}", "a.md"),
            page("/..", "a.md"),
            page("support", "a.md"),
            page("/support/terms", "a.md"),
            page("/ok", "a.md"),
            page("/ok", "a.md"),
            page("/profile/about", "a.md"),
            page("/feeds/recent", "a.md"),
            page("/b", "../a.md"),
            page("/c", "/a.md"),
            page("/d", "pages/a.txt"),
            page("/e", "pages\\..\\a.md"),
        ]));
        let plain = "must be a plain path, /segments of a-z, 0-9, - _ and ., no query or token";
        let within = "must be a .md file's path within the app file's directory";
        assert_eq!(
            problems,
            [
                "app.pages[0]: unknown key \"x\"".to_string(),
                "app.pages[0] must have the property \"title\"".to_string(),
                format!("app.pages[1].path: {plain}"),
                format!("app.pages[2].path: {plain}"),
                format!("app.pages[3].path: {plain}"),
                format!("app.pages[4].path: {plain}"),
                format!("app.pages[5].path: {plain}"),
                format!("app.pages[6].path: {plain}"),
                "app.pages[9].path: another page's too".to_string(),
                "app.pages[10].path: a tab's or a route's too".to_string(),
                "app.pages[11].path: a tab's or a route's too".to_string(),
                format!("app.pages[12].markdown: {within}"),
                format!("app.pages[13].markdown: {within}"),
                format!("app.pages[14].markdown: {within}"),
                format!("app.pages[15].markdown: {within}"),
            ]
        );
        // A tab's own path is no page's.
        let mut tabbed = grain.clone();
        tabbed["pages"] = json!([page("/home", "a.md")]);
        tabbed["tabs"][0]["path"] = json!("/home");
        assert_eq!(
            app_problems(&tabbed, "grain.social", views),
            ["app.pages[0].path: a tab's or a route's too"]
        );
    }

    /// An app file's `refresh`: a procedure's method and its service,
    /// nothing more.
    #[test]
    fn refresh_checked() {
        let views = view::views();
        let app = |refresh: Value| {
            json!({ "domain": "grain.social", "name": "Grain",
                "tabs": [{ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }],
                "refresh": refresh })
        };
        let check = |refresh: Value| app_problems(&app(refresh), "grain.social", views);
        let fine = json!({ "method": "social.grain.sync.indexRecords",
                           "service": "did:web:grain.social#grain_appview" });
        assert!(check(fine).is_empty());
        assert_eq!(
            check(json!("social.grain.sync.indexRecords")),
            ["app.refresh: must be an object, a procedure's method and service"]
        );
        assert_eq!(
            check(json!({ "method": "refresh", "service": "grain", "input": {} })),
            [
                "app.refresh.method: must be a method's NSID",
                "app.refresh.service: Not a service: grain (a DID with its service's #fragment, as did:web:api.bsky.app#bsky_appview)",
                "app.refresh.input: not a field of it",
            ]
        );
        // An app with none refreshes nothing.
        assert_eq!(refresh_of(&json!({}), &BTreeSet::new()), None);
    }

    /// An app file's `permissions`: a list of sets, each its NSID and the
    /// service its methods are called at, if any, and nothing else.
    #[test]
    fn permissions_checked() {
        let views = view::views();
        let app = |permissions: Value| {
            json!({ "domain": "grain.social", "name": "Grain",
                "tabs": [{ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }],
                "permissions": permissions })
        };
        let check = |p: Value| app_problems(&app(p), "grain.social", views);
        let fine = json!([
            { "include": "social.grain.authFull", "service": "did:web:grain.social#grain_appview" },
            { "include": "com.example.authBasic" },
        ]);
        assert!(check(fine.clone()).is_empty());
        assert_eq!(
            sets_of(&app(fine)),
            [
                Include {
                    nsid: "social.grain.authFull".into(),
                    service: Some("did:web:grain.social#grain_appview".into()),
                },
                Include {
                    nsid: "com.example.authBasic".into(),
                    service: None,
                },
            ]
        );
        let refused = "app.permissions: must be a list of 1 to 8 permission sets";
        for bad in [
            json!("social.grain.authFull"),
            json!([]),
            json!(vec![json!({ "include": "a.b.c" }); 9]),
        ] {
            assert_eq!(check(bad), [refused]);
        }
        assert_eq!(
            check(json!([
                "social.grain.authFull",
                { "include": "authFull", "service": "grain", "aud": "did:web:grain.social" },
                { "service": "did:web:grain.social#grain_appview" },
            ])),
            [
                "app.permissions[0]: must be an object, a set's include and service",
                "app.permissions[1].include: must be a permission set's NSID",
                "app.permissions[1].service: Not a service: grain (a DID with its service's #fragment, as did:web:api.bsky.app#bsky_appview)",
                "app.permissions[1].aud: not a field of it",
                "app.permissions[2].include: must be a permission set's NSID",
            ]
        );
        assert!(sets_of(&json!({})).is_empty());
    }

    /// An app file's shape, and each call drawing what a view draws.
    #[test]
    fn apps_checked() {
        let views = view::views();
        let check = |doc: Value| app_problems(&doc, "grain.social", views);
        let call = |name: &str, args: Value| json!({ "name": name, "args": args });
        let fine = json!({ "domain": "grain.social", "name": "Grain",
            "tabs": [
                { "label": "Home", "call": call("query", json!({ "method": "social.grain.feed.getFeed" })) },
                { "label": "Profile", "call": call("describe_app", json!({ "domain": "grain.social", "actor": "me" })),
                  "guest": call("list_records", json!({ "actor": "x", "collection": "fm.plyr.list" })) },
            ],
            "routes": [
                { "path": "/g/{a}/{r}", "call": call("get_record", json!({ "uri": "at://{a}/social.grain.gallery/{r}" })) },
                { "path": "/d/{a}/{r}", "tab": "Profile",
                  "call": call("get_record", json!({ "uri": "at://{a}/site.standard.document/{r}" })) },
            ] });
        assert_eq!(check(fine.clone()), Vec::<String>::new());
        // Routes are for those apps that have them.
        let mut tabs_alone = fine.clone();
        tabs_alone.as_object_mut().unwrap().remove("routes");
        assert_eq!(check(tabs_alone), Vec::<String>::new());
        assert_eq!(check(json!([])), ["app: must be an object"]);
        assert_eq!(
            check(json!({ "domain": "example.test", "name": " ", "routes": {} })),
            [
                "app.domain: must be grain.social, as its file is named",
                "app.name: required",
                "app.tabs: must be a list of one or more tabs",
                "app.routes: must be a list of routes",
            ]
        );
        let mut bad = fine;
        bad["tabs"][0] = json!({ "call": call("describe_repo", json!({ "actor": "x" })),
                                 "guest": call("describe_app", json!({ "domain": "example.test" })) });
        bad["tabs"][1]["guest"] = call("list_records", json!({ "collection": "a.b.c" }));
        bad["routes"][0]["path"] = json!("g");
        bad["routes"][0]["call"]["args"]["uri"] = json!("at://x/a.b.c/r");
        bad["routes"][1]["tab"] = json!("Home");
        assert_eq!(
            check(bad),
            [
                "app.tabs[0].label: required",
                "app.tabs[0].call: must be a call of query, describe_app, get_record or list_records",
                "app.tabs[0].guest: no view draws \"example.test\"",
                "app.tabs[1].guest: no view draws \"a.b.c\"",
                "app.routes[0].path: must be a path, starting with /",
                "app.routes[0].call: no view draws \"a.b.c\"",
                "app.routes[1].tab: must be a tab's label",
            ]
        );
    }

    /// A story's route: opened in the stories pager (`pager`), over its
    /// account's screen (`under`, a route's path its own binds) where its
    /// URL is loaded.
    #[test]
    fn pager_routes_checked() {
        let views = view::views();
        let call =
            json!({ "name": "get_record", "args": { "uri": "at://{a}/social.grain.gallery/{r}" } });
        let check = |story: Value| {
            let home = json!({ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } });
            let routes = json!([{ "path": "/p/{a}", "call": call }, story]);
            app_problems(
                &json!({ "domain": "grain.social", "name": "Grain", "tabs": [home], "routes": routes }),
                "grain.social",
                views,
            )
        };
        let story = |extra: Value| {
            let mut route = json!({ "path": "/p/{a}/s/{r}", "call": call });
            route
                .as_object_mut()
                .unwrap()
                .extend(extra.as_object().unwrap().clone());
            route
        };
        assert_eq!(
            check(story(json!({ "pager": true, "under": "/p/{a}" }))),
            Vec::<String>::new()
        );
        assert_eq!(check(story(json!({ "pager": true }))), Vec::<String>::new());
        assert_eq!(
            check(story(json!({ "pager": 1, "under": 2 }))),
            [
                "app.routes[1].pager: must be true",
                "app.routes[1].under: must be a path, starting with /"
            ]
        );
        assert_eq!(
            check(story(json!({ "under": "/q/{b}" }))),
            [
                "app.routes[1].under: only a pager's route has one",
                "app.routes[1].under: {b} is in no token of its path",
                "app.routes[1].under: no route's path is /q/{b}",
            ]
        );
    }

    /// A tab's `first`: a query of a method's NSID, the list's and each
    /// item's path dotted, and an NSID after which it is read again; no
    /// other key.
    #[test]
    fn tab_first_checked() {
        let views = view::views();
        let prefs = json!({ "name": "query", "args": { "method": "social.grain.actor.getPreferences",
                            "service": "did:web:grain.social#grain_appview", "params": {} } });
        let first = json!({ "call": prefs, "at": "preferences.@pinnedFeedsPref.items", "path": "path",
                            "after": "social.grain.actor.setPreference" });
        let check = |first: Value| {
            let home = json!({ "label": "Home", "path": "/", "first": first,
                               "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } });
            app_problems(
                &json!({ "domain": "grain.social", "name": "Grain", "tabs": [home] }),
                "grain.social",
                views,
            )
        };
        assert_eq!(check(first.clone()), Vec::<String>::new());
        let mut bare = first.clone();
        bare.as_object_mut().unwrap().remove("after");
        assert_eq!(check(bare), Vec::<String>::new());
        let mut bad = first.clone();
        bad["call"]["name"] = json!("describe_app");
        bad["at"] = json!("preferences..items");
        bad["path"] = json!("path.");
        bad["also"] = json!(true);
        assert_eq!(
            check(bad),
            [
                "app.tabs[0].first: unknown key \"also\"",
                "app.tabs[0].first.call: must be a query of a method's NSID",
                "app.tabs[0].first.at: must be a dotted path, no segment empty",
                "app.tabs[0].first.path: must be a dotted path, no segment empty",
            ]
        );
        let mut unnamed = first.clone();
        unnamed["call"]["args"]["method"] = json!("getPreferences");
        assert_eq!(
            check(unnamed),
            ["app.tabs[0].first.call: must be a query of a method's NSID"]
        );
        let mut missing = first.clone();
        missing.as_object_mut().unwrap().remove("path");
        assert_eq!(
            check(missing),
            ["app.tabs[0].first must have the property \"path\""]
        );
        let mut after = first;
        after["after"] = json!("set preference");
        assert_eq!(
            check(after),
            ["app.tabs[0].first.after must be a valid nsid"]
        );
        assert_eq!(
            check(json!("first")),
            ["app.tabs[0].first must be an object"]
        );
    }

    /// An app file's `head`: its site's name, its texts, an https picture
    /// and an account as @name; nothing else.
    #[test]
    fn app_head_checked() {
        let views = view::views();
        let tabs = json!([{ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }]);
        let check = |head: Value| {
            let doc =
                json!({ "domain": "grain.social", "name": "Grain", "tabs": tabs, "head": head });
            app_problems(&doc, "grain.social", views)
        };
        let fine = json!({ "siteName": "Grain", "title": "Grain: photo sharing", "description": "Galleries.",
                           "image": "https://grain.social/og.jpg", "imageAlt": "Photos", "twitter": "@grain_social" });
        assert_eq!(check(fine), Vec::<String>::new());
        assert_eq!(check(json!({ "siteName": "Grain" })), Vec::<String>::new());
        assert_eq!(check(json!("Grain")), ["app.head: must be an object"]);
        assert_eq!(
            check(
                json!({ "title": " ", "description": "x".repeat(301), "imageAlt": 3,
                          "image": "http://grain.social/og.jpg", "twitter": "grain", "x": 1 })
            ),
            [
                "app.head: unknown key \"x\"",
                "app.head.siteName: required",
                "app.head.title: must be text of 1 to 300 characters",
                "app.head.description: must be text of 1 to 300 characters",
                "app.head.imageAlt: must be text of 1 to 300 characters",
                "app.head.image: must be an https URL",
                "app.head.twitter: must be an account, as @name",
            ]
        );
        for bad in ["@", "@a-b", "@abcdefghijklmnop", "not a url"] {
            let problems = check(json!({ "siteName": "Grain", "twitter": bad, "image": bad }));
            assert_eq!(problems.len(), 2, "{bad}: {problems:?}");
        }
    }

    /// An app file's `frame`: what its lexicon describes, no key more at
    /// any level, its calls drawn, its icons a shell's, its picture on a
    /// tab, its hrefs paths or https, its sizes and bands in order.
    #[test]
    fn app_frame_checked() {
        let views = view::views();
        let query = |method: &str| json!({ "name": "query", "args": { "method": method } });
        let tabs = json!([{ "label": "Home", "call": query("social.grain.feed.getFeed") },
                          { "label": "Profile", "call": query("social.grain.actor.getPreferences") }]);
        let app = |frame: Option<Value>| {
            let mut doc = json!({ "domain": "grain.social", "name": "Grain", "tabs": tabs });
            if let Some(frame) = frame {
                doc["frame"] = frame;
            }
            doc
        };
        let check = |frame: Value| app_problems(&app(Some(frame)), "grain.social", views);
        // An app file with no frame is checked as ever.
        assert_eq!(
            app_problems(&app(None), "grain.social", views),
            Vec::<String>::new()
        );
        let fine = json!({
            "destinations": "tabs",
            "action": { "label": "Create", "icon": "imagePlus",
                        "call": query("social.grain.feed.getFeed") },
            "account": {
                "picture": { "tab": "Profile", "call": query("social.grain.actor.getProfile"),
                             "at": "avatar.url", "name": "displayName", "handle": "handle" },
                "items": [
                    { "label": "Settings", "icon": "settings", "call": query("social.grain.actor.getPreferences") },
                    { "host": "signOut", "label": "Log out", "icon": "logOut" },
                    { "host": "signIn", "about": "Share your photography" },
                ] },
            "links": [{ "label": "Terms", "href": "https://grain.social/terms" },
                      { "label": "About", "href": "/about" }],
            "aside": { "call": query("social.grain.feed.getFeed"), "width": 320 },
            "sizes": { "content": 600, "wide": 935 },
            "bands": { "rail": 600, "sidebar": 1200 },
        });
        assert_eq!(check(fine.clone()), Vec::<String>::new());
        assert_eq!(check(json!({})), Vec::<String>::new());
        // Unknown keys, at the top and below, each named.
        let mut extra = fine.clone();
        extra["x"] = json!(1);
        extra["account"]["items"][1]["y"] = json!(1);
        extra["sizes"]["z"] = json!(1);
        assert_eq!(
            check(extra),
            [
                "app.frame.account.items[1]: unknown key \"y\"",
                "app.frame.sizes: unknown key \"z\"",
                "app.frame: unknown key \"x\"",
            ]
        );
        // What its lexicon refuses, said where.
        assert_eq!(check(json!("tabs")), ["app.frame must be an object"]);
        let lexicon = |frame: Value| {
            let problems = check(frame);
            assert_eq!(problems.len(), 1, "{problems:?}");
            problems[0].clone()
        };
        for (frame, at) in [
            (
                json!({ "sizes": { "content": 319 } }),
                "app.frame.sizes.content",
            ),
            (json!({ "sizes": { "wide": 2401 } }), "app.frame.sizes.wide"),
            (json!({ "bands": { "rail": 100 } }), "app.frame.bands.rail"),
            (
                json!({ "bands": { "sidebar": 4001 } }),
                "app.frame.bands.sidebar",
            ),
            (
                json!({ "aside": { "call": query("social.grain.feed.getFeed"), "width": 100 } }),
                "app.frame.aside.width",
            ),
            (
                json!({ "links": vec![json!({ "label": "a", "href": "/a" }); 13] }),
                "app.frame.links",
            ),
            (
                json!({ "account": { "items": vec![json!({ "host": "signIn" }); 9] } }),
                "app.frame.account.items",
            ),
            (
                json!({ "action": { "label": "", "icon": "plus", "call": query("social.grain.feed.getFeed") } }),
                "app.frame.action.label",
            ),
            (
                json!({ "action": { "label": "Create" } }),
                "app.frame.action",
            ),
        ] {
            let said = lexicon(frame);
            assert!(said.starts_with(at), "{at}: {said}");
        }
        // Its own rules.
        let mut bad = fine;
        bad["destinations"] = json!("pages");
        bad["action"]["icon"] = json!("rocket");
        bad["action"]["call"] = query("a.b.c");
        bad["account"]["picture"] = json!({ "tab": "Home page", "call": query("not a method"), "at": "avatar..url",
                    "name": ".displayName", "handle": "handle." });
        bad["account"]["items"] = json!([
            { "label": "Settings", "call": query("a.b.c") },
            { "host": "signOut", "call": query("social.grain.feed.getFeed") },
            { "label": "Help" },
            { "host": "help" },
            { "host": "signOut", "about": "Bye" },
            { "host": "signOut" },
        ]);
        bad["links"] = json!([{ "label": "a", "href": "//x" }, { "label": "b", "href": "http://x.test" },
                              { "label": "c", "href": "terms" }]);
        bad["aside"]["call"] = json!({ "name": "describe_repo", "args": {} });
        bad["sizes"] = json!({ "content": 1000 });
        bad["bands"] = json!({ "rail": 1200 });
        assert_eq!(
            check(bad),
            [
                "app.frame.destinations: must be \"tabs\", the app's tabs",
                "app.frame.action.icon: must be one of catalog::FRAME_ICONS",
                "app.frame.action.call: no view draws \"a.b.c\"",
                "app.frame.account.picture.tab: must be a tab's label",
                "app.frame.account.picture.call: must be a query of a method's NSID",
                "app.frame.account.picture.at: must be a dotted path, no segment empty",
                "app.frame.account.picture.name: must be a dotted path, no segment empty",
                "app.frame.account.picture.handle: must be a dotted path, no segment empty",
                "app.frame.account.items[0].icon: required with a call",
                "app.frame.account.items[0].call: no view draws \"a.b.c\"",
                "app.frame.account.items[1]: takes a call or a host, not both",
                "app.frame.account.items[2]: needs a call or a host",
                "app.frame.account.items[3].host: must be signOut or signIn",
                "app.frame.account.items[4].about: a signIn item's alone",
                "app.frame.account.items[5].host: at most one signOut item",
                "app.frame.links[0].href: must be a path starting with / or an https URL",
                "app.frame.links[1].href: must be a path starting with / or an https URL",
                "app.frame.links[2].href: must be a path starting with / or an https URL",
                "app.frame.aside.call: must be a call of query, describe_app, get_record or list_records",
                "app.frame.sizes.wide: must be no narrower than content (1000)",
                "app.frame.bands.sidebar: must be wider than rail (1200)",
            ]
        );
        // A picture's call need not be a query a view draws, but a query.
        let mut picture = json!({ "account": { "picture": { "tab": "Home", "at": "avatar",
                                   "call": { "name": "get_record", "args": { "method": "a.b.c" } } } } });
        assert_eq!(
            check(picture.clone()),
            ["app.frame.account.picture.call: must be a query of a method's NSID"]
        );
        picture["account"]["picture"]["call"]["name"] = json!("query");
        assert_eq!(check(picture), Vec::<String>::new());
    }

    /// An app file's `signIn`: what its lexicon describes, no key it does
    /// not name, its links paths or https URLs, its typeahead at an https
    /// origin with scalar params and dotted paths.
    #[test]
    fn app_sign_in_checked() {
        let views = view::views();
        let query = json!({ "name": "query", "args": { "method": "social.grain.feed.getFeed" } });
        let check = |sign_in: Value| {
            let doc = json!({ "domain": "grain.social", "name": "Grain",
                              "tabs": [{ "label": "Home", "call": query }], "signIn": sign_in });
            app_problems(&doc, "grain.social", views)
        };
        let fine = json!({
            "title": "Log in with your atmosphere account",
            "text": "[What is an atmosphere account?](https://atmosphereaccount.com/)",
            "placeholder": "e.g. user.bsky.social",
            "legal": "By signing in you agree to our [Terms](/support/terms) and [Privacy](/support/privacy).",
            "create": { "text": "Don't have an account?", "label": "Create one" },
            "typeahead": { "url": "https://typeahead.waow.tech", "method": "tech.waow.typeahead.searchActors",
                           "param": "q", "params": { "limit": 5, "x": "y", "z": true },
                           "items": "actors", "did": "did", "handle": "handle", "name": "displayName",
                           "avatar": "avatar", "avatarFallback": "avatarFallback" },
        });
        assert_eq!(check(fine.clone()), Vec::<String>::new());
        assert_eq!(check(json!({ "title": "Sign in" })), Vec::<String>::new());
        // Unknown keys, at the top and below, each named.
        let mut extra = fine.clone();
        extra["x"] = json!(1);
        extra["create"]["y"] = json!(1);
        extra["typeahead"]["z"] = json!(1);
        assert_eq!(
            check(extra),
            [
                "app.signIn.create: unknown key \"y\"",
                "app.signIn.typeahead: unknown key \"z\"",
                "app.signIn: unknown key \"x\"",
            ]
        );
        // What its lexicon refuses, said where.
        assert_eq!(check(json!("Sign in")), ["app.signIn must be an object"]);
        let mut untitled = fine.clone();
        untitled.as_object_mut().unwrap().remove("title");
        assert_eq!(check(untitled).len(), 1);
        // Its rules past the lexicon.
        let with = |key: &str, at: &str, v: Value| {
            let mut s = fine.clone();
            match at {
                "" => s[key] = v,
                _ => s[at][key] = v,
            }
            check(s)
        };
        for (key, text) in [
            ("text", "[Here](javascript:alert(1))"),
            ("legal", "Our [Terms](//evil.test/terms)."),
            ("legal", "Our [Terms](http://grain.social/terms)."),
        ] {
            assert_eq!(
                with(key, "", json!(text)),
                [format!(
                    "app.signIn.{key}: each link must go to a path starting with / or an https URL"
                )],
                "{text}"
            );
        }
        for url in [
            "http://typeahead.waow.tech",
            "https://typeahead.waow.tech/xrpc",
            "https://typeahead.waow.tech/?a=b",
            "https://typeahead.waow.tech/#a",
            "https://me@typeahead.waow.tech",
        ] {
            assert_eq!(
                with("url", "typeahead", json!(url)),
                [
                    "app.signIn.typeahead.url: must be an https origin, as https://typeahead.waow.tech"
                ],
                "{url}"
            );
        }
        for params in [
            json!([5]),
            json!({ "limit": { "n": 5 } }),
            json!({ "q": null }),
        ] {
            assert_eq!(
                with("params", "typeahead", params.clone()),
                ["app.signIn.typeahead.params: must be an object of strings, numbers and booleans"],
                "{params}"
            );
        }
        for key in ["items", "did", "handle", "name", "avatar", "avatarFallback"] {
            assert_eq!(
                with(key, "typeahead", json!("a..b")),
                [format!(
                    "app.signIn.typeahead.{key}: must be a dotted path, no segment empty"
                )]
            );
        }
        // A typeahead's optional paths left out are no problem.
        let mut bare = fine.clone();
        for key in ["params", "name", "avatar", "avatarFallback"] {
            bare["typeahead"].as_object_mut().unwrap().remove(key);
        }
        assert_eq!(check(bare), Vec::<String>::new());
    }

    /// An app file's `push`: its calls procedures HUD has lexicons of,
    /// binding the device's token, and what a notification opens a route's
    /// path its fields fill.
    #[test]
    fn push_checked() {
        let views = view::views();
        let grain = "did:web:grain.social#grain_appview";
        let device = json!({ "serviceDid": "did:web:grain.social", "token": { "$token": true },
                             "platform": { "$platform": true }, "appId": { "$appId": true } });
        let procedure = |m: &str| json!({ "method": m, "service": grain, "input": device });
        let app = |push: Value| {
            json!({ "domain": "grain.social", "name": "Grain",
                "tabs": [{ "label": "Home", "call": { "name": "query", "args": { "method": "social.grain.feed.getFeed" } } }],
                "routes": [
                    { "path": "/profile/{actor}/gallery/{rkey}",
                      "call": { "name": "get_record", "args": { "uri": "at://{actor}/social.grain.gallery/{rkey}" } } },
                    { "path": "/profile/{actor}?tab={tab}",
                      "call": { "name": "describe_app", "args": { "domain": "grain.social", "actor": "{actor}" } } },
                ],
                "push": push })
        };
        let check = |push: Value| app_problems(&app(push), "grain.social", views);
        let fine = json!({
            "register": procedure("social.grain.notification.registerPush"),
            "unregister": procedure("social.grain.notification.unregisterPush"),
            "open": [
                { "when": { "type": "gallery-favorite", "uri": "at://{actor}/social.grain.gallery/{rkey}" },
                  "path": "/profile/{actor}/gallery/{rkey}" },
                { "when": { "did": "{actor:did}" }, "path": "/profile/{actor}" },
            ] });
        assert_eq!(check(fine.clone()), Vec::<String>::new());
        let call = |m: &str| view::Call {
            method: m.into(),
            service: grain.into(),
            input: device.clone(),
            deletes: false,
        };
        assert_eq!(
            push_calls(&app(fine.clone())),
            [
                call("social.grain.notification.registerPush"),
                call("social.grain.notification.unregisterPush")
            ]
        );
        // An app with no push makes no push calls; one may open nothing.
        assert!(push_calls(&json!({})).is_empty());
        let mut quiet = fine.clone();
        quiet.as_object_mut().unwrap().remove("open");
        assert_eq!(check(quiet), Vec::<String>::new());
        assert_eq!(check(json!([])), ["app.push: must be an object"]);
        assert_eq!(
            check(json!({ "register": "x", "open": {} })),
            [
                "app.push.register: required, a procedure's method, service and input",
                "app.push.unregister: required, a procedure's method, service and input",
                "app.push.open: must be a list of what a notification opens",
            ]
        );
        // A query is no procedure, and a method needs an NSID.
        let mut calls = fine.clone();
        calls["register"]["method"] = json!("social.grain.notification.getUnreadCount");
        calls["unregister"]["method"] = json!("unregister");
        assert_eq!(
            check(calls),
            [
                "app.push.register: social.grain.notification.getUnreadCount is a query, not a procedure",
                "app.push.unregister.method: must be a method's NSID",
            ]
        );
        // A service, the lexicon's input, and bindings of the device alone.
        let mut inputs = fine.clone();
        inputs["register"]["service"] = json!("grain");
        inputs["register"]["input"] = json!({ "serviceDid": "did:web:grain.social", "token": "abc",
            "platform": { "$platform": true, "x": 1 }, "appId": [{ "$bundle": true }], "extra": 1 });
        inputs["unregister"]["method"] = json!("example.test.unregister");
        let binds = "is no binding of a push call, which binds {\"$token\": true}, {\"$appId\": true} and {\"$platform\": true}";
        assert_eq!(
            check(inputs),
            [
                "app.push.register.service: Not a service: grain (a DID with its service's #fragment, as did:web:api.bsky.app#bsky_appview)".to_string(),
                "app.push.register: social.grain.notification.registerPush: input.extra is not an input of it".into(),
                format!("app.push.register.input.platform: $platform {binds}"),
                format!("app.push.register.input.appId[0]: $bundle {binds}"),
                "app.push.register.input: must hold the device's token, {\"$token\": true}".into(),
                "app.push.unregister: example.test.unregister: no lexicon".into(),
            ]
        );
        // What a notification opens: its fields' patterns, and a route's path they fill.
        let mut open = fine;
        open["open"] = json!([
            { "when": { "uri": 5 }, "path": "profile" },
            { "when": {}, "path": "/profile/{actor}/story/{rkey}" },
            { "when": { "did": "{actor}" }, "path": "/profile/{who}/gallery/{rkey}" },
        ]);
        assert_eq!(
            check(open),
            [
                "app.push.open[0].when: must be an object of the notification's fields, each a pattern",
                "app.push.open[0].path: must be a path, starting with /",
                "app.push.open[1].when: must be an object of the notification's fields, each a pattern",
                "app.push.open[1].path: {actor} is in no pattern of when",
                "app.push.open[1].path: {rkey} is in no pattern of when",
                "app.push.open[1].path: no route's path is /profile/{actor}/story/{rkey}",
                "app.push.open[2].path: {who} is in no pattern of when",
                "app.push.open[2].path: {rkey} is in no pattern of when",
            ]
        );
        assert_eq!(tokens("at://{a:did}/x/{r}/{open"), ["a", "r"]);
    }

    /// A file whose push falls short refuses startup, naming its file.
    #[test]
    fn a_bad_push_refuses_startup() {
        let dir = temp_dir("push");
        let mut example = app("app.bsky.graph.getLists");
        example["push"] = json!({ "register": {}, "unregister": {} });
        write(
            &dir,
            &[
                ("example.test.json", example),
                (
                    "views/v.json",
                    method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor"),
                ),
            ],
        );
        let file = dir.join("example.test.json").display().to_string();
        assert_eq!(
            load(&dir, true).unwrap_err(),
            [
                format!("{file}: app.push.register.method: must be a method's NSID"),
                format!("{file}: app.push.unregister.method: must be a method's NSID"),
            ]
        );
    }

    /// Every problem at once, each naming its file and where in it, as
    /// `hud check` prints them: an app file that is no JSON, a lexicon that
    /// is none, a view's problems (each of them), a view that is no JSON,
    /// two views drawing one method, a call of what is no procedure, and an
    /// app file's problems.
    #[test]
    fn every_problem_is_named() {
        let dir = temp_dir("every");
        let lists = method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor");
        let mut example = app("app.bsky.graph.getLists");
        example["routes"][0]["call"]["args"]["method"] = json!("app.bsky.graph.getStarterPacks");
        example.as_object_mut().unwrap().remove("name");
        std::fs::create_dir_all(dir.join("lexicons")).unwrap();
        write(
            &dir,
            &[
                ("example.test.json", example),
                ("views/a.json", lists.clone()),
                ("views/b.json", lists),
                ("views/broken.json", json!({ "method": "a.b.c", "nope": 1 })),
                (
                    "views/query.json",
                    method_view("app.bsky.graph.getList", "app.bsky.graph.getList"),
                ),
                ("lexicons/bad.json", json!({ "lexicon": 1 })),
            ],
        );
        std::fs::write(dir.join("views/json.json"), "{").unwrap();
        std::fs::write(dir.join("other.test.json"), "[").unwrap();
        let at = |f: &str| dir.join(f).display().to_string();
        assert_eq!(
            load(&dir, true).unwrap_err(),
            [
                format!(
                    "{}: EOF while parsing a list at line 1 column 1",
                    at("other.test.json")
                ),
                format!(
                    "{}: must be a lexicon document: lexicon 1, an NSID as its id, and defs",
                    at("lexicons/bad.json")
                ),
                format!("{}: view: unknown key \"nope\"", at("views/broken.json")),
                format!(
                    "{}: view.description: must be one line of text, 200 characters at most",
                    at("views/broken.json")
                ),
                format!(
                    "{}: view.service: a method view names the service it calls",
                    at("views/broken.json")
                ),
                format!(
                    "{}: view: a method view needs its query mode",
                    at("views/broken.json")
                ),
                format!(
                    "{}: EOF while parsing an object at line 1 column 1",
                    at("views/json.json")
                ),
                format!(
                    "{}: {} draws app.bsky.graph.getLists too",
                    at("views/b.json"),
                    at("views/a.json")
                ),
                format!(
                    "{}: app.bsky.graph.getList is a query, not a procedure",
                    at("views/query.json")
                ),
                format!("{}: app.name: required", at("example.test.json")),
                format!(
                    "{}: app.routes[0].call: no view draws \"app.bsky.graph.getStarterPacks\"",
                    at("example.test.json")
                ),
            ]
        );
    }

    /// An app file's `hud` is the HUD versions it runs on: a HUD older than
    /// it needs refuses it, saying so and nothing else, since the rest is
    /// written for a newer HUD; a HUD it runs on checks the rest and loads
    /// it. A `hud` that is no semver requirement is refused.
    #[test]
    fn an_app_needing_a_newer_hud_is_refused() {
        let dir = temp_dir("version");
        let mut example = app("app.bsky.graph.getLists");
        example["hud"] = json!(">=0.2.0");
        let lists = method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor");
        write(
            &dir,
            &[
                ("example.test.json", example.clone()),
                ("views/v.json", lists),
                ("views/newer.json", json!({ "method": "a.b.c" })),
            ],
        );
        let version = |v: &str| semver::Version::parse(v).unwrap();
        let file = dir.join("example.test.json").display().to_string();
        assert_eq!(
            load_as(&dir, true, &version("0.1.0")).unwrap_err(),
            [format!(
                "{file}: app.hud: the app needs HUD >=0.2.0, and this HUD is 0.1.0: run a newer HUD"
            )]
        );
        let newer = dir.join("views/newer.json").display().to_string();
        let problems = load_as(&dir, true, &version("0.2.0")).unwrap_err();
        assert!(
            problems.iter().all(|p| p.starts_with(&newer)),
            "{problems:?}"
        );
        std::fs::remove_file(&newer).unwrap();
        let loaded = load_as(&dir, true, &version("0.3.1")).unwrap();
        assert_eq!(loaded.apps, ["example.test"]);
        for wrong in [json!(2), json!("two")] {
            example["hud"] = wrong;
            write(&dir, &[("example.test.json", example.clone())]);
            assert_eq!(
                load(&dir, true).unwrap_err(),
                [format!(
                    "{file}: app.hud: must be the HUD versions the app runs on, as \">=0.2.0\""
                )]
            );
        }
    }

    /// An app file's `kits.oldest` is the oldest kit its clients still
    /// serve, a HUD version from the oldest kit's; its views are read for
    /// what that kit would not draw (`kit::warnings`), a warning, never a
    /// refusal: nothing in the catalog is newer than it yet.
    #[test]
    fn an_app_says_the_oldest_kit_it_serves() {
        let dir = temp_dir("kits");
        let mut example = app("app.bsky.graph.getLists");
        example["kits"] = json!({ "oldest": crate::kit::OLDEST });
        let lists = method_view("app.bsky.graph.getLists", "social.grain.graph.muteActor");
        write(
            &dir,
            &[
                ("example.test.json", example.clone()),
                ("views/v.json", lists),
            ],
        );
        let loaded = load(&dir, true).unwrap();
        assert_eq!(loaded.apps, ["example.test"]);
        assert!(loaded.warnings.is_empty(), "{:?}", loaded.warnings);
        let file = dir.join("example.test.json").display().to_string();
        for wrong in [
            json!("0.2.0"),
            json!({}),
            json!({ "oldest": "soon" }),
            json!({ "oldest": "0.1.9" }),
            json!({ "oldest": "0.2.0", "newest": "1.0.0" }),
        ] {
            example["kits"] = wrong.clone();
            write(&dir, &[("example.test.json", example.clone())]);
            assert_eq!(
                load(&dir, true).unwrap_err(),
                [format!(
                    "{file}: app.kits: must be {{ oldest }}, the oldest kit its clients still serve, a HUD version from 0.2.0, as \"0.2.0\""
                )],
                "{wrong}"
            );
        }
    }

    /// An app's lexicons (`lexicons/`, at any depth): HUD checks its views'
    /// calls and its push against them, one in place of the bundled
    /// lexicon of its NSID, and reads them as it serves
    /// (`Views::lexicon`). A file that is no lexicon, one of HUD's own, or a
    /// second of one NSID is refused.
    #[test]
    fn an_app_ships_its_lexicons() {
        let dir = temp_dir("lexicons");
        let thing = json!({ "lexicon": 1, "id": "example.test.doThing", "defs": { "main": {
            "type": "procedure", "input": { "encoding": "application/json", "schema": {
                "type": "object", "required": ["actor"],
                "properties": { "actor": { "type": "string" } } } } } } });
        let register = json!({ "method": "example.test.doThing",
                               "service": "did:web:api.bsky.app#bsky_appview",
                               "input": { "actor": { "$token": true } } });
        let mut example = app("app.bsky.graph.getLists");
        example["push"] = json!({ "register": register, "unregister": register });
        let lists = method_view("app.bsky.graph.getLists", "example.test.doThing");
        write(
            &dir,
            &[("example.test.json", example), ("views/v.json", lists)],
        );
        let at = |f: &str| dir.join(f).display().to_string();
        assert_eq!(
            load(&dir, true).unwrap_err(),
            [
                format!("{}: example.test.doThing: no lexicon", at("views/v.json")),
                format!(
                    "{}: app.push.register: example.test.doThing: no lexicon",
                    at("example.test.json")
                ),
                format!(
                    "{}: app.push.unregister: example.test.doThing: no lexicon",
                    at("example.test.json")
                ),
            ]
        );
        std::fs::create_dir_all(dir.join("lexicons/example/test")).unwrap();
        let mut mute = (*crate::lexicon::bundled("social.grain.graph.muteActor").unwrap()).clone();
        mute["defs"]["main"]["input"]["schema"]["required"] = json!(["actor", "reason"]);
        write(
            &dir,
            &[
                ("lexicons/example/test/doThing.json", thing.clone()),
                ("lexicons/mute.json", mute),
            ],
        );
        let loaded = load(&dir, true).unwrap();
        let views = &loaded.views;
        assert_eq!(
            views.lexicon("example.test.doThing").unwrap()["id"],
            "example.test.doThing"
        );
        assert_eq!(
            views.lexicon("social.grain.graph.muteActor").unwrap()["defs"]["main"]["input"]["schema"]
                ["required"],
            json!(["actor", "reason"])
        );
        assert!(views.lexicon("app.bsky.graph.getLists").is_none());
        let docs = views.lexicon_docs();
        assert_eq!(docs.len(), crate::lexicon::all_bundled().count() + 1);
        assert_eq!(docs[0]["id"], "example.test.doThing");
        // A view's call is checked against the app's lexicon of its NSID.
        let muting = method_view("app.bsky.graph.getList", "social.grain.graph.muteActor");
        write(&dir, &[("views/w.json", muting)]);
        assert_eq!(
            load(&dir, true).unwrap_err(),
            [format!(
                "{}: social.grain.graph.muteActor: input.reason is required",
                at("views/w.json")
            )]
        );
        std::fs::remove_file(dir.join("views/w.json")).unwrap();
        // Files that are no lexicon of the app's own.
        let lexicon = |id: &str| json!({ "lexicon": 1, "id": id, "defs": {} });
        write(
            &dir,
            &[
                ("lexicons/a.json", lexicon("nope")),
                ("lexicons/b.json", lexicon("place.hud.view")),
                ("lexicons/c.json", thing),
            ],
        );
        std::fs::write(dir.join("lexicons/d.json"), "{").unwrap();
        std::fs::write(dir.join("lexicons/README.md"), "Not a lexicon").unwrap();
        assert_eq!(
            load(&dir, true).unwrap_err(),
            [
                format!(
                    "{}: must be a lexicon document: lexicon 1, an NSID as its id, and defs",
                    at("lexicons/a.json")
                ),
                format!(
                    "{}: place.hud.view is HUD's own lexicon, which no app ships",
                    at("lexicons/b.json")
                ),
                format!(
                    "{}: EOF while parsing an object at line 1 column 1",
                    at("lexicons/d.json")
                ),
                format!(
                    "{}: another file is example.test.doThing too",
                    at("lexicons/example/test/doThing.json")
                ),
            ]
        );
    }
}