makeover_webview/build/

drift.rs

//! Checks that a hand-written frontend still agrees with the crate that
//! generates its siblings.
//!
//! The generated files cannot drift: they ask makeover-geometry for the answer.
//! The hand-written ones state it, and a stylesheet or a script that disagrees
//! with the crate raises no error at any point. It is a rule that quietly
//! stops matching where it used to. Cheaper to read a panic naming the line.
//!
//! Deliberately assertions and not substitutions. A JS or CSS file that has to
//! be generated to be correct stops being readable on its own, and it is worth
//! something that you can still open the frontend in a browser and have it
//! work.

use std::path::{Path, PathBuf};

use crate::Emit;
use makeover_geometry::{Density, SizeClass};

/// The declaration this check reads. Shared vocabulary, not a parameter: two
/// apps and a server naming the same string want the same name for it.
const CONST_NAME: &str = "TOUCH_DENSITY";

/// The capability sniffs the media query replaced, so neither can come back by
/// copy-paste.
///
/// Both ask the hardware what it has rather than what is pointing at the
/// screen, so both say yes to a touchscreen laptop driving a mouse.
const SNIFFS: &[&str] = &["ontouchstart", "maxTouchPoints"];

/// Fail the build if a JS copy of the touch-density query has drifted from
/// [`Density::Touch`].
///
/// Every `.js` file under `js_dir`, recursively, must state the crate's own
/// media condition in a `const TOUCH_DENSITY = '...'`, at least one file must
/// declare it, and no file may name a capability sniff.
///
/// The string is the crate's and no app gets a say in it, which is why this
/// check takes no policy argument. The generated `geometry.css` already keys
/// its touch gap overrides on the same condition, so the gestures and the
/// spacing agree by construction rather than by two people remembering.
///
/// Emits `cargo:rerun-if-changed` for every file it read.
///
/// # Panics
///
/// If `js_dir` cannot be read, if no declaration is found, or if any file
/// disagrees with the crate. A build script has nowhere useful to return an
/// error to, and a frontend that disagrees with its own stylesheet is worse
/// than a failed build.
pub fn check_touch_density(js_dir: impl AsRef<Path>) {
    let js_dir = js_dir.as_ref();
    let want = Density::Touch.media_condition();
    let mut wrong: Vec<String> = Vec::new();
    let mut found = 0usize;

    let files = js_files(js_dir);
    for path in &files {
        let src = std::fs::read_to_string(path)
            .unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
        let name = path
            .strip_prefix(js_dir)
            .unwrap_or(path)
            .display()
            .to_string();

        for (offset, literal) in touch_density_literals(&src) {
            found += 1;
            if literal != want {
                wrong.push(format!(
                    "  {name}:{}  {CONST_NAME} = '{literal}'",
                    line_of(&src, offset)
                ));
            }
        }

        for needle in SNIFFS {
            if let Some(offset) = src.find(needle) {
                wrong.push(format!(
                    "  {name}:{}  {needle} -- device sniff, not a density question",
                    line_of(&src, offset)
                ));
            }
        }
    }

    assert!(
        found > 0,
        "no {CONST_NAME} literal found under {}.\n\n\
         A frontend that asks whether it is being touched states\n\
         makeover_geometry::Density::Touch's media condition in a const of that\n\
         name, and this check exists to keep every copy equal to it. If the\n\
         const was renamed, rename it back rather than dropping the check; if\n\
         this frontend genuinely asks no density question, drop the call.",
        js_dir.display()
    );

    assert!(
        wrong.is_empty(),
        "hand-written touch detection disagrees with makeover_geometry::Density.\n\n\
         Density::Touch.media_condition() is: {want}\n\n\
         Wrong:\n{}\n\n\
         Fix the JS to state the crate's string. Never widen it to catch a\n\
         device the query misses: density is what is pointing at the screen,\n\
         and a laptop with a touchscreen and a mouse is a pointer device.",
        wrong.join("\n")
    );

    for path in &files {
        println!("cargo:rerun-if-changed={}", path.display());
    }
    // The directory too, so a file added under it reruns the check: a
    // rerun keyed only on the files that existed last time never sees the
    // one somebody just copied in.
    println!("cargo:rerun-if-changed={}", js_dir.display());
}

/// Every `.js` file under `dir`, recursively, sorted.
fn js_files(dir: &Path) -> Vec<PathBuf> {
    files_with_extension(dir, "js")
}

/// Every file under `dir` with extension `ext`, recursively, sorted.
///
/// Recursive because a consumer's frontend is not always one flat directory:
/// the Tauri apps keep `js/*.js`, the server keeps subdirectories under
/// `static/`, and a check that silently skipped the nested half would report
/// clean on the files most likely to have been copied.
fn files_with_extension(dir: &Path, ext: &str) -> Vec<PathBuf> {
    let mut out = Vec::new();
    let mut stack = vec![dir.to_path_buf()];
    while let Some(d) = stack.pop() {
        for entry in std::fs::read_dir(&d)
            .unwrap_or_else(|e| panic!("read {}: {e}", d.display()))
            .flatten()
        {
            let path = entry.path();
            if path.is_dir() {
                stack.push(path);
            } else if path.extension().is_some_and(|x| x == ext) {
                out.push(path);
            }
        }
    }
    out.sort();
    out
}

/// `(byte offset of the declaration, the literal's contents)` for every
/// `const TOUCH_DENSITY = '...'` in a JS source.
fn touch_density_literals(src: &str) -> Vec<(usize, &str)> {
    let mut out = Vec::new();
    let mut at = 0;
    while let Some(i) = src[at..].find(CONST_NAME) {
        let start = at + i;
        at = start + CONST_NAME.len();
        // Only the declaration states the string; a use site reads the const.
        let Some(rest) = src[at..].strip_prefix(" = ") else {
            continue;
        };
        let open = at + " = ".len();
        let Some(quote @ ('\'' | '"')) = rest.chars().next() else {
            continue;
        };
        let body = open + 1;
        if let Some(j) = src[body..].find(quote) {
            out.push((start, &src[body..body + j]));
            at = body + j + 1;
        }
    }
    out
}

fn line_of(src: &str, offset: usize) -> usize {
    src[..offset].matches('\n').count() + 1
}

/// Which files a check reads.
#[derive(Debug, Clone)]
enum Source {
    /// A frontend directory, scanned recursively.
    Frontend(PathBuf),
    /// A named list of files.
    Files(Vec<PathBuf>),
}

impl Source {
    fn files<P: AsRef<Path>>(paths: &[P]) -> Self {
        Self::Files(paths.iter().map(|p| p.as_ref().to_path_buf()).collect())
    }
}

/// Fail the build if a hand-written breakpoint has drifted from [`SizeClass`].
///
/// Every pixel width named by a media query must be a [`SizeClass`] boundary or
/// one of the [`tuning`](Self::tuning) widths.
///
/// ```no_run
/// makeover_webview::build::drift::Breakpoints::in_frontend("frontend")
///     .tuning(&[1400])
///     .run();
/// ```
///
/// Without this, moving `SizeClass::Medium::min_px` regenerates the emitted
/// stylesheets and leaves every hand-written query behind, and the result is a
/// stylesheet that disagrees with itself at the old boundary rather than an
/// error.
///
/// The generated stylesheets are scanned too, and pass by construction: they
/// ask makeover-geometry for the number rather than stating it. Scanning them
/// means a consumer never has to name which files are hand-written.
#[derive(Debug, Clone)]
#[must_use = "a check does nothing until it is run"]
pub struct Breakpoints {
    source: Source,
    tuning: Vec<u16>,
}

impl Breakpoints {
    /// Every `.css` under `frontend/css` and every `.js` under `frontend/js`,
    /// recursively.
    pub fn in_frontend(frontend: impl AsRef<Path>) -> Self {
        Self {
            source: Source::Frontend(frontend.as_ref().to_path_buf()),
            tuning: Vec::new(),
        }
    }

    /// A named list of files rather than a tree.
    ///
    /// For a frontend whose generated and hand-written files share a directory,
    /// with nothing to point a directory scan at: the MNW server keeps both
    /// under `static/` beside a bundler's output. The list is hand-maintained,
    /// and a stylesheet nobody adds to it is unchecked rather than failing, so
    /// prefer [`in_frontend`](Self::in_frontend) where the layout allows it.
    ///
    /// A `.js` path is read as script and anything else as stylesheet.
    pub fn files<P: AsRef<Path>>(paths: &[P]) -> Self {
        Self {
            source: Source::files(paths),
            tuning: Vec::new(),
        }
    }

    /// Widths inside a shell where something reflows without the shell
    /// changing: a dashboard dropping from three columns to two, a pane's width
    /// cap ending.
    ///
    /// The one thing an app gets a say in. A shell boundary is a [`SizeClass`]
    /// edge and belongs to makeover-geometry; nothing switches shells at a
    /// tuning width, so it does not move when a size class does. Each entry
    /// owes a note beside it saying what it tunes: this list is where a genuine
    /// boundary goes to hide from the check.
    pub fn tuning(mut self, widths: &[u16]) -> Self {
        self.tuning.extend_from_slice(widths);
        self
    }

    /// Run the check. Emits `cargo:rerun-if-changed` for every file it read,
    /// and for the scanned directories.
    ///
    /// # Panics
    ///
    /// If a directory or a listed file cannot be read (a listed path that no
    /// longer exists is a check covering less than it says), or if any width
    /// is neither a size-class boundary nor a tuning width. A build script has
    /// nowhere useful to return an error to.
    pub fn run(&self) {
        match &self.source {
            Source::Frontend(frontend) => {
                let mut files = files_with_extension(&frontend.join("css"), "css");
                files.extend(js_files(&frontend.join("js")));
                check_paths(&files, &self.tuning, Some(frontend));
                // The directories too, so a file added later reruns it.
                println!("cargo:rerun-if-changed={}", frontend.join("css").display());
                println!("cargo:rerun-if-changed={}", frontend.join("js").display());
            }
            Source::Files(paths) => check_paths(paths, &self.tuning, None),
        }
    }
}

/// The check itself. `root`, when given, is stripped from reported paths.
fn check_paths(paths: &[PathBuf], tuning_widths: &[u16], root: Option<&Path>) {
    let allowed = allowed_widths(tuning_widths);
    let mut stale: Vec<String> = Vec::new();

    for path in paths {
        let raw = std::fs::read_to_string(path)
            .unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
        let name = match root {
            Some(root) => display_name(root, path),
            None => path.display().to_string(),
        };

        if path.extension().is_some_and(|x| x == "js") {
            // No declarations in JS, so any parenthesised width is a query.
            for (offset, width) in js_widths(&blank(&raw, Lang::Js)) {
                if !width.is_allowed(&allowed) {
                    stale.push(format!("  {name}:{}  ({width})", line_of(&raw, offset)));
                }
            }
            continue;
        }

        // Comments first: a note about a breakpoint that used to be here is
        // prose, not a rule, and should not fail a build.
        let src = blank(&raw, Lang::Css);
        for (offset, condition) in media_conditions(&src) {
            for width in media_widths(condition) {
                if !width.is_allowed(&allowed) {
                    stale.push(format!(
                        "  {name}:{}  @media{condition}  ({width})",
                        line_of(&src, offset)
                    ));
                }
            }
        }
    }

    assert!(
        stale.is_empty(),
        "hand-written breakpoints disagree with makeover_geometry::SizeClass.\n\n\
         Allowed: {allowed:?}\n\
         ({:?} come from SizeClass; {tuning_widths:?} were passed as tuning widths.)\n\n\
         Stale:\n{}\n\n\
         Size classes are written in range syntax, `(width < 600px)`, because\n\
         `(max-width: 599px)` leaves 599.5px in no class. If a size class moved,\n\
         update these to match. If one of these is a new\n\
         tuning width inside the wide shell rather than a shell boundary, add it\n\
         to the caller's tuning list with a note saying what it tunes.\n\n\
         Best of all, make the rule dimensional so it needs no threshold: a grid\n\
         wants repeat(auto-fit, minmax(<content floor>, 1fr)) and a size wants\n\
         clamp(). A threshold is for what appears and disappears.",
        allowed
            .iter()
            .filter(|px| !tuning_widths.contains(px))
            .collect::<Vec<_>>(),
        stale.join("\n")
    );

    for path in paths {
        println!("cargo:rerun-if-changed={}", path.display());
    }
}

/// A path as the frontend sees it, for an error a reader can act on.
fn display_name(frontend: &Path, path: &Path) -> String {
    path.strip_prefix(frontend)
        .unwrap_or(path)
        .display()
        .to_string()
}

/// Every width a hand-written media query is allowed to name.
///
/// Read out of [`SizeClass::media_condition`] rather than typed, which is the
/// whole point: that is the one place the numbers come from, and a bump in
/// makeover-geometry has to reach the stylesheet through here.
fn allowed_widths(tuning_widths: &[u16]) -> Vec<u16> {
    let mut widths: Vec<u16> = SizeClass::all()
        .iter()
        .flat_map(|c| media_widths(&c.media_condition()))
        .map(|width| match width {
            Width::Px(px) => px,
            Width::Other(raw) => {
                panic!("makeover-geometry wrote a size-class width this check cannot read: {raw}")
            }
        })
        .collect();
    widths.extend_from_slice(tuning_widths);
    widths.sort_unstable();
    widths.dedup();
    widths
}

/// A width named in a media condition.
#[derive(Debug, Clone, PartialEq, Eq)]
enum Width {
    /// A whole number of CSS pixels: `600px`, or `37.5em` at the 16px a media
    /// query's `em` is measured against.
    Px(u16),
    /// Anything this cannot state in whole pixels: `599.98px`, `50vw`, `40ch`.
    /// Never a boundary, so always reported.
    Other(String),
}

impl Width {
    fn is_allowed(&self, allowed: &[u16]) -> bool {
        matches!(self, Self::Px(px) if allowed.contains(px))
    }
}

impl std::fmt::Display for Width {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Px(px) => write!(f, "{px}px"),
            Self::Other(raw) => f.write_str(raw),
        }
    }
}

/// Every width in a media condition, in the order it appears.
///
/// Reads both spellings of a width feature: `(max-width: 599px)` and range
/// syntax, `(width < 600px)` or `(600px <= width < 840px)`, which is what
/// [`SizeClass::media_condition`] writes. A feature group is any innermost
/// `( ... )` naming `width` and not `device-width`, and every length inside it
/// counts. Units are read rather than assumed: `48em` is 768px, not 48.
fn media_widths(condition: &str) -> Vec<Width> {
    width_groups(condition)
        .into_iter()
        .flat_map(|(_, group)| lengths(group))
        .collect()
}

/// `(byte offset, inner text)` of every innermost parenthesised group that
/// names a width feature.
fn width_groups(src: &str) -> Vec<(usize, &str)> {
    let mut out = Vec::new();
    let mut open = None;
    for (i, c) in src.char_indices() {
        match c {
            '(' => open = Some(i),
            ')' => {
                if let Some(start) = open.take() {
                    let inner = &src[start + 1..i];
                    if names_width(inner) {
                        out.push((start, inner));
                    }
                }
            }
            '\n' => open = None,
            _ => {}
        }
    }
    out
}

/// Whether a feature group is about the viewport's width: `width`,
/// `min-width` or `max-width` as a whole word, not `device-width` and not a
/// longer identifier that ends in it.
fn names_width(inner: &str) -> bool {
    inner.match_indices("width").any(|(at, _)| {
        let before = &inner[..at];
        let prefix_ok = before.is_empty()
            || before.ends_with("min-")
            || before.ends_with("max-")
            || before
                .chars()
                .next_back()
                .is_some_and(|c| !c.is_ascii_alphanumeric() && c != '-' && c != '_');
        let after = inner[at + "width".len()..].chars().next();
        prefix_ok && after.is_none_or(|c| !c.is_ascii_alphanumeric() && c != '-' && c != '_')
    })
}

/// Every `<number><unit>` in a feature group, as a [`Width`].
fn lengths(group: &str) -> Vec<Width> {
    let bytes = group.as_bytes();
    let mut out = Vec::new();
    let mut i = 0;
    while i < bytes.len() {
        let starts_number = bytes[i].is_ascii_digit()
            && (i == 0 || !(bytes[i - 1].is_ascii_alphanumeric() || bytes[i - 1] == b'-'));
        if !starts_number {
            i += 1;
            continue;
        }
        let start = i;
        while i < bytes.len() && (bytes[i].is_ascii_digit() || bytes[i] == b'.') {
            i += 1;
        }
        let number = &group[start..i];
        let unit_start = i;
        while i < bytes.len() && bytes[i].is_ascii_alphabetic() {
            i += 1;
        }
        let unit = &group[unit_start..i];
        if unit.is_empty() {
            continue;
        }
        let raw = &group[start..i];
        let scale = match unit {
            "px" => Some(1.0),
            "em" | "rem" => Some(16.0),
            _ => None,
        };
        let px = scale.and_then(|scale| number.parse::<f64>().ok().map(|n| n * scale));
        out.push(match px {
            Some(px) if px.fract() == 0.0 && px >= 0.0 && px <= f64::from(u16::MAX) => {
                // Whole and in range, checked above.
                #[allow(clippy::cast_possible_truncation, clippy::cast_sign_loss)]
                Width::Px(px as u16)
            }
            _ => Width::Other(raw.to_string()),
        });
    }
    out
}

/// `(byte offset of the `@media`, the condition text before the `{`)`.
fn media_conditions(css: &str) -> Vec<(usize, &str)> {
    let mut out = Vec::new();
    let mut at = 0;
    while let Some(i) = css[at..].find("@media") {
        let start = at + i;
        let after = start + "@media".len();
        match css[after..].find('{') {
            Some(j) => {
                out.push((start, &css[after..after + j]));
                at = after + j;
            }
            None => break,
        }
    }
    out
}

/// `(byte offset, width)` for every width feature in a JS source.
///
/// The parentheses are the whole test, and they have to be: a media condition
/// is always parenthesized and a CSS declaration never is, so `'max-width:
/// 320px'` in an inline-style string is not a breakpoint and must not read as
/// one. Range syntax, `(width < 600px)`, is read the same way as in a
/// stylesheet.
fn js_widths(src: &str) -> Vec<(usize, Width)> {
    width_groups(src)
        .into_iter()
        .filter(|(_, group)| is_feature(group))
        .flat_map(|(offset, group)| lengths(group).into_iter().map(move |w| (offset, w)))
        .collect()
}

/// Whether a parenthesised group in script is a media feature rather than a
/// call's arguments: `(max-width: 600px)` or `(width < 600px)`, not
/// `Math.max(width, 600)`.
fn is_feature(group: &str) -> bool {
    let group = group.trim();
    let colon = ["min-width", "max-width", "width"].iter().any(|name| {
        group
            .strip_prefix(name)
            .is_some_and(|rest| rest.trim_start().starts_with(':'))
    });
    colon || group.contains(['<', '>'])
}

/// Which language a source is, for [`blank`].
#[derive(Clone, Copy, PartialEq, Eq)]
enum Lang {
    /// Comments and string contents both go: neither is a rule, and
    /// `content: "/*"` must not open a comment.
    Css,
    /// Comments go and strings stay, because a media query in script is a
    /// string (`matchMedia('(width < 600px)')`). A `/*` or `//` inside one is
    /// still text, not a comment.
    Js,
}

/// Blank the parts of `src` that are not code, keeping every byte offset.
///
/// One scanner for both readers, and it tracks string literals so a comment
/// opener inside one is text. Blanked characters become spaces, except that a
/// newline stays a newline so line numbers still line up.
fn blank(src: &str, lang: Lang) -> String {
    #[derive(Clone, Copy)]
    enum State {
        Code,
        Block,
        Line,
        Quoted(char),
    }
    // A blanked character becomes as many spaces as it had bytes, so every
    // byte offset into the result is the same byte offset into `src`.
    let blank_into = |out: &mut String, c: char| {
        if c == '\n' {
            out.push('\n');
        } else {
            out.extend(std::iter::repeat_n(' ', c.len_utf8()));
        }
    };
    let mut out = String::with_capacity(src.len());
    let mut state = State::Code;
    let mut chars = src.chars().peekable();
    while let Some(c) = chars.next() {
        match state {
            State::Code => match c {
                '/' if chars.peek() == Some(&'*') => {
                    chars.next();
                    out.push_str("  ");
                    state = State::Block;
                }
                '/' if lang == Lang::Js && chars.peek() == Some(&'/') => {
                    chars.next();
                    out.push_str("  ");
                    state = State::Line;
                }
                '"' | '\'' | '`' if lang == Lang::Js || c != '`' => {
                    out.push(c);
                    state = State::Quoted(c);
                }
                _ => out.push(c),
            },
            State::Block => {
                if c == '*' && chars.peek() == Some(&'/') {
                    chars.next();
                    out.push_str("  ");
                    state = State::Code;
                } else {
                    blank_into(&mut out, c);
                }
            }
            State::Line => {
                blank_into(&mut out, c);
                if c == '\n' {
                    state = State::Code;
                }
            }
            State::Quoted(quote) => {
                let mut keep = |c: char| {
                    if lang == Lang::Js {
                        out.push(c);
                    } else {
                        blank_into(&mut out, c);
                    }
                };
                if c == quote {
                    out.push(c);
                    state = State::Code;
                } else if c == '\\' {
                    keep(c);
                    if let Some(escaped) = chars.next() {
                        keep(escaped);
                    }
                } else {
                    keep(c);
                }
            }
        }
    }
    out
}

/// Blank every `@layer <name> { ... }` block whose name is in `names`, keeping
/// byte offsets and line breaks. Comments and strings are skipped while the
/// braces are matched, the same way [`blank`] reads them.
fn drop_layers(css: &str, names: &[&str]) -> String {
    if names.is_empty() {
        return css.to_owned();
    }
    let scan = blank(css, Lang::Css);
    let scan = scan.as_bytes();
    let mut out = css.as_bytes().to_vec();
    let mut at = 0;
    while let Some(found) = find_from(scan, b"@layer", at) {
        let mut i = found + b"@layer".len();
        while i < scan.len() && scan[i].is_ascii_whitespace() {
            i += 1;
        }
        let start = i;
        while i < scan.len() && (scan[i].is_ascii_alphanumeric() || matches!(scan[i], b'-' | b'_'))
        {
            i += 1;
        }
        let name = &css[start..i];
        while i < scan.len() && scan[i].is_ascii_whitespace() {
            i += 1;
        }
        if i >= scan.len() || scan[i] != b'{' || !names.contains(&name) {
            at = found + 1;
            continue;
        }
        let mut depth = 0usize;
        let mut end = scan.len();
        for (k, &byte) in scan.iter().enumerate().skip(i) {
            match byte {
                b'{' => depth += 1,
                b'}' => {
                    depth -= 1;
                    if depth == 0 {
                        end = k + 1;
                        break;
                    }
                }
                _ => {}
            }
        }
        for byte in &mut out[found..end] {
            if *byte != b'\n' {
                *byte = b' ';
            }
        }
        at = end;
    }
    String::from_utf8(out).unwrap_or_else(|_| css.to_owned())
}

fn find_from(haystack: &[u8], needle: &[u8], from: usize) -> Option<usize> {
    haystack
        .get(from..)?
        .windows(needle.len())
        .position(|window| window == needle)
        .map(|at| at + from)
}

/// A reviewed exception to [`Vocabulary`]: a collision the app has read and
/// kept, with a note beside it saying why.
///
/// It expires when the collision does. An exception that no longer collides
/// fails the check, since an unused licence is where the next real collision
/// lands unnoticed.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Allow<'a> {
    /// A hand-written rule on a generated class takes one of its properties.
    Class {
        /// The class, unprefixed as the stylesheet spells it.
        class: &'a str,
        /// The property both set.
        property: &'a str,
    },
    /// A bare element rule takes a property the generated sheet sets on a class
    /// that element carries.
    Element {
        /// The element the rule selects.
        element: &'a str,
        /// The generated class it reaches.
        class: &'a str,
        /// The property both set.
        property: &'a str,
    },
}

impl<'a> Allow<'a> {
    /// See [`Allow::Class`].
    pub const fn class(class: &'a str, property: &'a str) -> Self {
        Self::Class { class, property }
    }

    /// See [`Allow::Element`].
    pub const fn element(element: &'a str, class: &'a str, property: &'a str) -> Self {
        Self::Element {
            element,
            class,
            property,
        }
    }
}

/// Fail the build if a hand-written stylesheet takes a property the generated
/// one already sets, on the same class or on an element that carries it.
///
/// The generated sheet sits in `@layer makeover`. App CSS beats it whatever the
/// specificity, either by being unlayered or by sitting in a layer the app's
/// order statement puts after `makeover`, so an app declaration for a property
/// makeover already sets does not merge with it: it wins, silently, and the
/// design system's version of that component stops applying, and nothing looks.
///
/// # Two passes, because a rule can carry no class
///
/// The class pass compares an app `.button` against the generated `.button`.
/// It reads rules by the classes in their selectors, so a rule with no class in
/// it is invisible to it, and `button { color: var(--content) }` is exactly
/// that: it sets the property the generated `.button` sets on every described
/// act, `.button[data-tone="danger"]`'s tone included, which draws a
/// destructive act like an ordinary one.
///
/// The element pass reads that case. `crate::vocabulary::ELEMENT_CLASSES`
/// says which generated classes an element can carry (CSS cannot say it, and
/// the renderer can), and a bare element rule taking a property the design
/// system sets on one of those classes is the same defect as the class case.
///
/// Two things are not reported, both deliberately:
///
///   - A scoped rule (`.page button`). It reaches the elements inside one
///     region rather than every one of them, so whether it lands on a described
///     act depends on where that act renders. The certain case is the one this
///     reads.
///   - A property the app names on the class itself, from a rule that outranks
///     the element rule. Both are the app's and both sit in the same layer, so
///     that one contest is settled by specificity, and what reaches the design
///     system is the class rule, which the class pass has already reported
///     or reviewed. The rank matters: `.field` does not beat
///     `input[type="text"]`, and a handoff written as the weaker of the two is
///     a remedy that looks written and is not.
///
/// # Why properties and not class names
///
/// A shared class name is not by itself a divergence. An app `.badge` that sets
/// shape while the generated `.badge` sets colour is a correct split, and a
/// check on names would ask for it to be deleted. On properties, the split is
/// what the check enforces.
///
/// # The exception list
///
/// [`Allow::class`] names a `(class, property)` pair this app has reviewed and
/// kept.
/// Deciding which are legitimate here would need a selector matcher, and a check
/// that guesses wrong about specificity fails correct builds, so the app
/// declares it instead, the same shape as quasi-webview's `RENDERER_OWN`.
///
/// A reviewed pairing is a claim about who owns a property, and it expires when
/// the design system takes the property back.
///
/// [`Allow::element`] is the same thing one pass down: an element rule reaching
/// a generated class that has been read and kept.
///
/// The remedy is usually neither. A later layer can hand the property back
/// with `revert-layer`, which says "whatever the design system set here, keep
/// it" on the arms makeover actually paints, and that is a statement in the
/// stylesheet rather than a note in a build script. Handoffs are not reported by
/// either pass.
///
/// A pair that stops colliding fails too. A licence nobody is using is where
/// the next real collision lands and reads as company.
///
/// ```no_run
/// use makeover_webview::build::drift::{Allow, Vocabulary};
///
/// Vocabulary::in_frontend("frontend")
///     .generated(&["layout.css"])
///     // Reviewed: the card's shadow is the app's, on the hover arm only.
///     .allow(Allow::class("card", "box-shadow"))
///     .run(&makeover_webview::Emit::default());
/// ```
#[derive(Debug, Clone)]
#[must_use = "a check does nothing until it is run"]
pub struct Vocabulary<'a> {
    source: Source,
    generated: Vec<&'a str>,
    upstream: Vec<&'a str>,
    allowed: Vec<Allow<'a>>,
    beneath: Vec<&'a str>,
}

impl<'a> Vocabulary<'a> {
    /// Every `.css` under `frontend/css`, recursively.
    pub fn in_frontend(frontend: impl AsRef<Path>) -> Self {
        Self::from(Source::Frontend(frontend.as_ref().to_path_buf()))
    }

    /// A named list of stylesheets rather than a tree.
    ///
    /// For a frontend whose generated and hand-written sheets share a
    /// directory. Same trade as [`Breakpoints::files`]: the list is
    /// hand-maintained, and a stylesheet nobody adds to it is unchecked.
    pub fn files<P: AsRef<Path>>(paths: &[P]) -> Self {
        Self::from(Source::files(paths))
    }

    fn from(source: Source) -> Self {
        Self {
            source,
            generated: Vec::new(),
            upstream: Vec::new(),
            allowed: Vec::new(),
            beneath: Vec::new(),
        }
    }

    /// Sheets this crate writes, which are skipped: the generated file setting
    /// a generated property is the point. Relative to `frontend/css` for
    /// [`in_frontend`](Self::in_frontend); matched against the end of each path
    /// for [`files`](Self::files).
    pub fn generated(mut self, names: &[&'a str]) -> Self {
        self.generated.extend_from_slice(names);
        self
    }

    /// The text of stylesheets that sit between makeover and the app and own
    /// the classes they style as makeover owns its own.
    ///
    /// quasi-webview's `SCREEN_CSS` is the case. This crate cannot name it,
    /// since quasi builds on this crate and not the other way round, so the app
    /// that links both hands it in. A hand-written sheet is checked against
    /// makeover's sheet and every upstream sheet together. A file whose text
    /// *is* an upstream sheet, the copy an app serves from its frontend, is
    /// checked against makeover alone and never read as clashing with itself.
    pub fn upstream(mut self, sheets: &[&'a str]) -> Self {
        self.upstream.extend_from_slice(sheets);
        self
    }

    /// Cascade layers the app orders before `makeover`, by name.
    ///
    /// A rule inside one loses to every generated rule whatever its selector,
    /// so it cannot take a property from the design system and is not read.
    /// The usual case is a reset: `@layer reset, makeover, ...` with
    /// `* { margin: 0; padding: 0 }` inside `@layer reset { }` clears browser
    /// defaults without zeroing the generated spacing. The order itself lives
    /// in the app's markup, which this check does not read, so naming a layer
    /// here is the app stating that order.
    pub fn beneath(mut self, layers: &[&'a str]) -> Self {
        self.beneath.extend_from_slice(layers);
        self
    }

    /// A reviewed exception. See [`Allow`].
    pub fn allow(mut self, allow: Allow<'a>) -> Self {
        self.allowed.push(allow);
        self
    }

    /// Several reviewed exceptions, for a list the app keeps as a `const`.
    pub fn allowing(mut self, allows: impl IntoIterator<Item = Allow<'a>>) -> Self {
        self.allowed.extend(allows);
        self
    }

    /// Run the check against the stylesheet `opts` generates. Emits
    /// `cargo:rerun-if-changed` for every file it read.
    ///
    /// # Panics
    ///
    /// If a directory or listed file cannot be read, if any hand-written sheet
    /// takes a generated property without an [`Allow`], or if an [`Allow`] no
    /// longer collides. A build script has nowhere useful to return an error
    /// to, and an app quietly overriding its own design system is worse than a
    /// failed build.
    pub fn run(&self, opts: &Emit) {
        let classes: Vec<(&str, &str)> = self
            .allowed
            .iter()
            .filter_map(|allow| match *allow {
                Allow::Class { class, property } => Some((class, property)),
                Allow::Element { .. } => None,
            })
            .collect();
        let elements: Vec<(&str, &str, &str)> = self
            .allowed
            .iter()
            .filter_map(|allow| match *allow {
                Allow::Element {
                    element,
                    class,
                    property,
                } => Some((element, class, property)),
                Allow::Class { .. } => None,
            })
            .collect();
        match &self.source {
            Source::Frontend(frontend) => {
                let css = frontend.join("css");
                let files: Vec<PathBuf> = files_with_extension(&css, "css")
                    .into_iter()
                    .filter(|p| {
                        let name = p.strip_prefix(&css).unwrap_or(p).display().to_string();
                        !self.generated.contains(&name.as_str())
                    })
                    .collect();
                check_vocabulary_paths(
                    &files,
                    opts,
                    Some(frontend),
                    &self.upstream,
                    &self.beneath,
                    &classes,
                    &elements,
                );
                // The directory too, so a stylesheet added later reruns it.
                println!("cargo::rerun-if-changed={}", css.display());
            }
            Source::Files(paths) => {
                let files: Vec<PathBuf> = paths
                    .iter()
                    .filter(|p| !self.generated.iter().any(|name| p.ends_with(name)))
                    .cloned()
                    .collect();
                check_vocabulary_paths(
                    &files,
                    opts,
                    None,
                    &self.upstream,
                    &self.beneath,
                    &classes,
                    &elements,
                );
            }
        }
    }
}

/// The check itself. `root`, when given, is stripped from reported paths.
fn check_vocabulary_paths(
    paths: &[PathBuf],
    opts: &Emit,
    root: Option<&Path>,
    upstream: &[&str],
    beneath: &[&str],
    allowed: &[(&str, &str)],
    allowed_elements: &[(&str, &str, &str)],
) {
    let makeover = crate::vocabulary::declarations_by_class(&crate::stylesheet(opts));
    // What a hand-written sheet answers to: makeover's classes and every
    // upstream sheet's, merged per class.
    let mut owned = makeover.clone();
    for sheet in upstream {
        for (class, properties) in crate::vocabulary::declarations_by_class(sheet) {
            owned.entry(class).or_default().extend(properties);
        }
    }
    let mut clashes: Vec<String> = Vec::new();
    let mut seen: Vec<(String, String)> = Vec::new();
    let mut element_clashes: Vec<String> = Vec::new();
    let mut element_seen: Vec<(String, String, String)> = Vec::new();

    for path in paths {
        println!("cargo::rerun-if-changed={}", path.display());
        let raw = std::fs::read_to_string(path)
            .unwrap_or_else(|e| panic!("read {}: {e}", path.display()));
        let name = match root {
            Some(root) => display_name(root, path),
            None => path.display().to_string(),
        };
        // An upstream sheet served from the frontend answers to makeover alone:
        // measured against itself every declaration in it would clash.
        let generated = if upstream.contains(&raw.as_str()) {
            &makeover
        } else {
            &owned
        };
        // A layer ordered before `makeover` cannot beat it, so its rules are
        // not read. See `Vocabulary::beneath`.
        let raw = drop_layers(&raw, beneath);
        // Read the app's sheet the same way the crate reads its own, or the two
        // sides are not comparable.
        let local = crate::vocabulary::declarations_by_class(&raw);
        for (class, properties) in &local {
            let Some(theirs) = generated.get(class) else {
                continue;
            };
            for property in properties.intersection(theirs) {
                seen.push((class.clone(), property.clone()));
                if allowed.contains(&(class.as_str(), property.as_str())) {
                    continue;
                }
                clashes.push(format!("  {name}  .{class} {{ {property} }}"));
            }
        }

        // The second pass: a rule carrying no class at all, which the first one
        // cannot see. What the app says about the class itself settles the
        // pair, but only from a rule that outranks the element rule. Both are
        // the app's and both are in the same layer, so this one contest is
        // decided by specificity. `.field` does not beat `input[type="text"]`.
        let mentioned = crate::vocabulary::mentions_by_class(&raw);
        let by_element = crate::vocabulary::declarations_by_element(&raw);
        for (element, properties) in &by_element {
            for class in crate::vocabulary::classes_for_element(element, opts) {
                let Some(theirs) = generated.get(&class) else {
                    continue;
                };
                for (property, rank) in properties {
                    if !theirs.contains(property) {
                        continue;
                    }
                    // A tie goes to the class rule: at equal specificity the
                    // later rule wins, and a remedy is written after the rule
                    // it remedies.
                    let spoken_for = mentioned
                        .get(&class)
                        .and_then(|properties| properties.get(property))
                        .is_some_and(|theirs| theirs >= rank);
                    if spoken_for {
                        continue;
                    }
                    element_seen.push((element.clone(), class.clone(), property.clone()));
                    if allowed_elements.contains(&(
                        element.as_str(),
                        class.as_str(),
                        property.as_str(),
                    )) {
                        continue;
                    }
                    element_clashes.push(format!(
                        "  {name}  {element} {{ {property} }}  beats  .{class} {{ {property} }}"
                    ));
                }
            }
        }
    }

    assert!(
        clashes.is_empty(),
        "{} hand-written declaration(s) take a property the generated stylesheet, \
         or an upstream sheet named to this check, already sets on the same \
         class. App CSS wins over @layer makeover, whether by a later layer or \
         by being unlayered, so each of these wins over the design system \
         silently:\n{}\n\nDelete the declaration, or, if \
         it is a deliberate pairing on a different selector arm, add \
         (class, property) to this check's allowed list and say why beside it. \
         Count the consumers before deciding a divergence is worth keeping.",
        clashes.len(),
        clashes.join("\n")
    );

    assert!(
        element_clashes.is_empty(),
        "{} hand-written element rule(s) take a property the generated \
         stylesheet sets on a class that element carries. App CSS wins over \
         @layer makeover, whether by a later layer or by being unlayered, so a \
         described component rendered on one of these elements loses the \
         design system's version of that property silently, which can draw a \
         destructive act like an ordinary one:\n{}\n\nHand the \
         property back on the arms makeover paints \
         (`.{{class}}:disabled {{ color: revert-layer }}`), scope the element \
         rule so it stops reaching described markup, or add \
         (element, class, property) to this check's allowed-elements list and \
         say why beside it.",
        element_clashes.len(),
        element_clashes.join("\n")
    );

    let stale: Vec<&(&str, &str)> = allowed
        .iter()
        .filter(|(class, property)| {
            !seen.contains(&((*class).to_string(), (*property).to_string()))
        })
        .collect();
    assert!(
        stale.is_empty(),
        "the allowed list declares {stale:?}, which no longer collides with \
         anything. Delete the entries: an exception nobody is using is where the \
         next real collision lands and reads as company."
    );

    let stale: Vec<&(&str, &str, &str)> = allowed_elements
        .iter()
        .filter(|(element, class, property)| {
            !element_seen.contains(&(
                (*element).to_string(),
                (*class).to_string(),
                (*property).to_string(),
            ))
        })
        .collect();
    assert!(
        stale.is_empty(),
        "the allowed-elements list declares {stale:?}, which no longer collides \
         with anything. Delete the entries: an exception nobody is using is \
         where the next real collision lands and reads as company."
    );
}

/// Whether `haystack` names `class` whole, rather than as part of a longer
/// name: `min-1` must not be read as used because `min-16` is, and `row` must
/// not be read as used because `row-flex` or `flex-row` is.
fn haystack_names(haystack: &str, class: &str) -> bool {
    let part = |c: char| c.is_ascii_alphanumeric() || c == '-' || c == '_';
    haystack.match_indices(class).any(|(at, found)| {
        haystack[..at].chars().next_back().is_none_or(|c| !part(c))
            && haystack[at + found.len()..]
                .chars()
                .next()
                .is_none_or(|c| !part(c))
    })
}

/// Warn when the generated vocabulary has grown dead, and fail when it grows
/// deader than the recorded high-water mark.
///
/// A generated class no markup emits is a rule shipped to every user for
/// nothing. Some dead vocabulary is normal, so the count alone is not a
/// failure; what this checks is the direction. Recording the count in the
/// build script makes a change that worsens it fail rather than go unnoticed.
///
/// One-sided, the same shape as the MNW server's `frontend_globals` seal:
/// exceeding `high_water` fails, coming in under it warns and asks for the seal
/// to be lowered. A build that fails because dead CSS was deleted would teach
/// the wrong lesson.
///
/// `markup` is every file that can carry a class: templates, `.js`, `.html`,
/// and any Rust that writes markup. A class is counted as used if its name
/// appears whole in any of them, which is deliberately generous. A stricter reading
/// would need to know how each app builds its class strings, and a check that
/// guesses wrong fails a correct build.
///
/// # Panics
///
/// If a listed file cannot be read, or if more classes are unused than
/// `high_water`.
pub fn check_vocabulary_use<P: AsRef<Path>>(markup: &[P], opts: &Emit, high_water: usize) {
    let generated = crate::vocabulary::names(opts);
    let mut haystack = String::new();
    for path in markup {
        let path = path.as_ref();
        println!("cargo::rerun-if-changed={}", path.display());
        haystack.push_str(
            &std::fs::read_to_string(path)
                .unwrap_or_else(|e| panic!("read {}: {e}", path.display())),
        );
        haystack.push('\n');
    }

    // A ladder is one piece of vocabulary, not one per rung. A column carries
    // whichever `min-N` rung its floor lands on and a table whichever `short-N`
    // rung its essentials need, so no site names every rung and counting each
    // would seal the dead count at the ladder's length. A ladder is used if any
    // rung is, and counted once if none is.
    const LADDERS: &[&str] = &["min-", "short-"];
    let rung_of = |class: &str| -> Option<&'static str> {
        let name = class.strip_prefix(opts.class_prefix)?;
        LADDERS.iter().copied().find(|ladder| {
            name.strip_prefix(ladder)
                .is_some_and(|n| !n.is_empty() && n.bytes().all(|b| b.is_ascii_digit()))
        })
    };
    let mut unused: Vec<String> = generated
        .iter()
        .filter(|class| rung_of(class).is_none() && !haystack_names(&haystack, class))
        .cloned()
        .collect();
    for ladder in LADDERS {
        let rungs: Vec<&String> = generated
            .iter()
            .filter(|class| rung_of(class) == Some(ladder))
            .collect();
        if !rungs.is_empty() && !rungs.iter().any(|class| haystack_names(&haystack, class)) {
            unused.push(format!("{}{ladder}N", opts.class_prefix));
        }
    }

    assert!(
        unused.len() <= high_water,
        "{} of {} generated classes are emitted by no markup, above the recorded {}. \
         The vocabulary grew or the markup stopped using it:\n{}",
        unused.len(),
        generated.len(),
        high_water,
        unused
            .iter()
            .map(|c| format!("  .{c}"))
            .collect::<Vec<_>>()
            .join("\n")
    );

    if unused.len() < high_water {
        println!(
            "cargo::warning=dead makeover vocabulary is down to {} from a sealed {}; \
             lower the seal so it cannot grow back",
            unused.len(),
            high_water
        );
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::fmt::Write as _;

    fn scratch(name: &str) -> PathBuf {
        let dir =
            std::env::temp_dir().join(format!("makeover-drift-{}-{name}", std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).expect("create scratch");
        dir
    }

    fn write(dir: &Path, name: &str, src: &str) {
        if let Some(parent) = dir.join(name).parent() {
            std::fs::create_dir_all(parent).unwrap();
        }
        std::fs::write(dir.join(name), src).unwrap();
    }

    fn declaring() -> String {
        format!(
            "const {CONST_NAME} = '{}';\n",
            Density::Touch.media_condition()
        )
    }

    #[test]
    fn the_crates_own_string_passes() {
        let dir = scratch("ok");
        write(&dir, "touch.js", &declaring());
        check_touch_density(&dir);
    }

    #[test]
    #[should_panic(expected = "disagrees with makeover_geometry::Density")]
    fn a_drifted_literal_fails() {
        let dir = scratch("drift");
        write(&dir, "touch.js", &declaring());
        write(
            &dir,
            "haptics.js",
            &format!("const {CONST_NAME} = '(pointer: coarse)';\n"),
        );
        check_touch_density(&dir);
    }

    #[test]
    #[should_panic(expected = "device sniff")]
    fn the_sniff_cannot_come_back() {
        let dir = scratch("sniff");
        write(&dir, "touch.js", &declaring());
        write(&dir, "legacy.js", "if ('ontouchstart' in window) {}\n");
        check_touch_density(&dir);
    }

    #[test]
    #[should_panic(expected = "no TOUCH_DENSITY literal found")]
    fn a_frontend_that_states_nothing_fails() {
        let dir = scratch("empty");
        write(&dir, "app.js", "export const x = 1;\n");
        check_touch_density(&dir);
    }

    #[test]
    fn a_use_site_is_not_a_declaration() {
        // The const is read far more often than it is declared, and a read
        // states no string. Counting one as a declaration would make the
        // `found > 0` assertion pass on a frontend that only imports it.
        let src =
            format!("import {{ {CONST_NAME} }} from './touch.js';\nmatchMedia({CONST_NAME});\n");
        assert!(touch_density_literals(&src).is_empty());
    }

    #[test]
    fn nested_files_are_read() {
        // The server keeps its scripts in subdirectories, and the nested half
        // is the half most likely to be a copy.
        let dir = scratch("nested");
        write(&dir, "touch.js", &declaring());
        write(&dir, "screens/legacy.js", "navigator.maxTouchPoints > 0;\n");
        let files = js_files(&dir);
        assert_eq!(files.len(), 2);
    }

    #[test]
    fn a_non_js_file_is_ignored() {
        let dir = scratch("nonjs");
        write(&dir, "touch.js", &declaring());
        write(&dir, "styles.css", "body { }\n");
        assert_eq!(js_files(&dir).len(), 1);
    }

    fn frontend(name: &str) -> PathBuf {
        let dir = scratch(name);
        std::fs::create_dir_all(dir.join("css")).unwrap();
        std::fs::create_dir_all(dir.join("js")).unwrap();
        dir
    }

    /// A width every size class agrees is a boundary.
    fn boundary() -> u16 {
        SizeClass::Medium.min_px()
    }

    #[test]
    fn the_crates_own_boundaries_pass() {
        let dir = frontend("bp-ok");
        write(
            &dir,
            "css/styles.css",
            &format!("@media (min-width: {}px) {{ body {{ }} }}\n", boundary()),
        );
        Breakpoints::in_frontend(&dir).run();
    }

    #[test]
    #[should_panic(expected = "disagree with makeover_geometry::SizeClass")]
    fn a_stale_css_width_fails() {
        let dir = frontend("bp-css");
        write(&dir, "css/styles.css", "@media (max-width: 768px) { }\n");
        Breakpoints::in_frontend(&dir).run();
    }

    #[test]
    #[should_panic(expected = "disagree with makeover_geometry::SizeClass")]
    fn a_stale_js_width_fails() {
        let dir = frontend("bp-js");
        write(&dir, "js/shell.js", "matchMedia('(max-width: 768px)');\n");
        Breakpoints::in_frontend(&dir).run();
    }

    #[test]
    fn a_declared_tuning_width_passes() {
        let dir = frontend("bp-tuning");
        write(&dir, "css/styles.css", "@media (min-width: 1400px) { }\n");
        Breakpoints::in_frontend(&dir).tuning(&[1400]).run();
    }

    #[test]
    fn a_width_in_a_comment_is_prose() {
        // The note explaining which breakpoint used to be here is not a rule,
        // and failing a build on documentation would teach people to delete it.
        let dir = frontend("bp-comment");
        write(
            &dir,
            "css/styles.css",
            "/* was @media (max-width: 768px) until the size classes landed */\n",
        );
        Breakpoints::in_frontend(&dir).run();
    }

    #[test]
    fn an_unparenthesized_width_is_not_a_breakpoint() {
        // A JS string building an inline style states `max-width: 320px` with
        // no parentheses. It is a declaration, not a query, and the first
        // version of this check failed the build on one.
        let dir = frontend("bp-inline");
        write(
            &dir,
            "js/style.js",
            "el.style.cssText = 'max-width: 320px; display: block';\n",
        );
        Breakpoints::in_frontend(&dir).run();
    }

    #[test]
    fn nested_css_is_read() {
        // Same argument as the touch check: the nested half is the half most
        // likely to be a copy.
        let dir = frontend("bp-nested");
        write(
            &dir,
            "css/screens/detail.css",
            "@media (max-width: 768px) { }\n",
        );
        let found = std::panic::catch_unwind(|| Breakpoints::in_frontend(&dir).run());
        assert!(found.is_err(), "a nested stylesheet must be scanned");
    }

    #[test]
    fn a_named_list_is_checked() {
        let dir = frontend("bp-list");
        write(&dir, "css/style.css", "@media (max-width: 768px) { }\n");
        let listed = dir.join("css/style.css");
        let err = std::panic::catch_unwind(|| Breakpoints::files(&[&listed]).run()).unwrap_err();
        let msg = err.downcast_ref::<String>().expect("String payload");
        assert!(msg.contains("style.css:1"), "got: {msg}");
    }

    #[test]
    #[should_panic(expected = "read ")]
    fn a_listed_file_that_is_gone_fails() {
        // The list is hand-maintained, so a path that stopped existing is a
        // check quietly covering less than it claims. Louder than skipping it.
        let dir = frontend("bp-missing");
        Breakpoints::files(&[dir.join("css/never-written.css")]).run();
    }

    #[test]
    fn a_listed_js_file_is_parsed_as_script() {
        // The unparenthesized-declaration rule is what separates the two, and
        // picking the parser off the extension is the whole difference.
        let dir = frontend("bp-list-js");
        write(
            &dir,
            "js/style.js",
            "el.style.cssText = 'max-width: 320px';\n",
        );
        Breakpoints::files(&[dir.join("js/style.js")]).run();
    }

    #[test]
    fn the_error_names_the_file_and_line() {
        let dir = frontend("bp-message");
        write(
            &dir,
            "css/styles.css",
            "body { }\n@media (max-width: 768px) { }\n",
        );
        let err = std::panic::catch_unwind(|| Breakpoints::in_frontend(&dir).run()).unwrap_err();
        let msg = err
            .downcast_ref::<String>()
            .expect("panic payload is a String");
        assert!(msg.contains("css/styles.css:2"), "got: {msg}");
    }

    #[test]
    fn a_rule_restating_an_upstream_class_fails_and_its_served_copy_does_not() {
        // quasi-webview's sheet owns `.run`'s gap the way makeover owns
        // `.card`'s shadow, and an app redrawing it wins silently the same way.
        let upstream = ".tile-set { gap: 4px; }\n";
        let dir = scratch("vocab-upstream");
        write(&dir, "css/quasi.css", upstream);
        write(&dir, "css/styles.css", ".tile-set { gap: 0; }\n");
        let err = std::panic::catch_unwind(|| {
            Vocabulary::in_frontend(&dir)
                .upstream(&[upstream])
                .run(&Emit::default());
        })
        .unwrap_err();
        let msg = err
            .downcast_ref::<String>()
            .expect("panic payload is a String");
        assert!(
            msg.contains("css/styles.css  .tile-set { gap }"),
            "got: {msg}"
        );
        assert!(
            !msg.contains("css/quasi.css"),
            "the served copy clashed with itself: {msg}"
        );

        // Without the upstream sheet named, the same tree passes, which is the
        // blind spot this closes.
        Vocabulary::in_frontend(&dir).run(&Emit::default());
    }

    #[test]
    fn a_rule_restating_a_generated_class_fails_and_names_it() {
        let dir = scratch("vocab-clash");
        // `.card` is makeover's. An app rule for it beats the generated one,
        // because app CSS is unlayered and the generated sheet is not.
        write(
            &dir,
            "css/styles.css",
            "body { color: red; }\n.card { box-shadow: none; }\n",
        );
        let err = std::panic::catch_unwind(|| Vocabulary::in_frontend(&dir).run(&Emit::default()))
            .unwrap_err();
        let msg = err
            .downcast_ref::<String>()
            .expect("panic payload is a String");
        assert!(msg.contains(".card"), "got: {msg}");
        assert!(msg.contains("box-shadow"), "got: {msg}");
        assert!(msg.contains("css/styles.css"), "got: {msg}");
    }

    #[test]
    fn an_app_class_of_its_own_is_left_alone() {
        let dir = scratch("vocab-clean");
        write(
            &dir,
            "css/styles.css",
            ".task-list-container { overflow: auto; }\n.day-plan-slot { height: 1rem; }\n",
        );
        Vocabulary::in_frontend(&dir).run(&Emit::default());
    }

    #[test]
    fn the_generated_sheet_is_skipped_rather_than_reported_against_itself() {
        let dir = scratch("vocab-generated");
        let opts = Emit::default();
        write(&dir, "css/layout.css", &crate::stylesheet(&opts));
        // Without the skip this is the loudest failure possible: every class in
        // the vocabulary, reported as a clash with the vocabulary.
        Vocabulary::in_frontend(&dir)
            .generated(&["layout.css"])
            .run(&opts);
    }

    #[test]
    fn a_prefixed_app_is_checked_against_its_own_prefix() {
        let dir = scratch("vocab-prefix");
        let opts = Emit::new().class_prefix("mo-");
        // Bare `.card` is the app's own class once the generated sheet writes
        // `.mo-card`, so this has to pass.
        write(&dir, "css/styles.css", ".card { box-shadow: none; }\n");
        Vocabulary::in_frontend(&dir).run(&opts);

        let dir = scratch("vocab-prefix-clash");
        write(&dir, "css/styles.css", ".mo-card { box-shadow: none; }\n");
        assert!(std::panic::catch_unwind(|| Vocabulary::in_frontend(&dir).run(&opts)).is_err());
    }

    #[test]
    fn a_class_shared_without_a_shared_property_is_left_alone() {
        let dir = scratch("vocab-additive");
        // The generated `.cell-value` sets only the text colour, so an app
        // setting its shape shares the class and takes nothing from it.
        write(
            &dir,
            "css/styles.css",
            ".cell-value { padding: 2px; border-radius: 3px; font-weight: 600; }\n",
        );
        Vocabulary::in_frontend(&dir).run(&Emit::default());
    }

    #[test]
    fn a_reviewed_pair_passes_and_stops_passing_when_it_stops_colliding() {
        let dir = scratch("vocab-allowed");
        write(&dir, "css/styles.css", ".card { box-shadow: none; }\n");
        Vocabulary::in_frontend(&dir)
            .allow(Allow::class("card", "box-shadow"))
            .run(&Emit::default());

        // The same licence against a sheet that no longer collides has to fail,
        // or the list only ever grows.
        let dir = scratch("vocab-allowed-stale");
        write(&dir, "css/styles.css", ".card { padding: 2px; }\n");
        let err = std::panic::catch_unwind(|| {
            Vocabulary::in_frontend(&dir)
                .allow(Allow::class("card", "box-shadow"))
                .run(&Emit::default());
        })
        .unwrap_err();
        let msg = err
            .downcast_ref::<String>()
            .expect("panic payload is a String");
        assert!(msg.contains("no longer collides"), "got: {msg}");
    }

    #[test]
    fn an_element_rule_clobbering_a_generated_class_fails_and_names_all_three() {
        let dir = scratch("vocab-element");
        // The defect that shipped for months: no class in the selector, so the
        // class pass sees nothing, and every described act in the app takes the
        // app's bevel instead of the design system's.
        write(&dir, "css/styles.css", "select { box-shadow: none; }\n");
        let err = std::panic::catch_unwind(|| Vocabulary::in_frontend(&dir).run(&Emit::default()))
            .unwrap_err();
        let msg = err
            .downcast_ref::<String>()
            .expect("panic payload is a String");
        assert!(msg.contains("select {"), "got: {msg}");
        assert!(msg.contains(".field"), "got: {msg}");
        assert!(msg.contains("box-shadow"), "got: {msg}");
        assert!(msg.contains("css/styles.css"), "got: {msg}");
    }

    #[test]
    fn a_universal_reset_after_the_design_system_is_caught() {
        // goingson and MNW both opened with `* { margin: 0; padding: 0 }` in a
        // layer after `makeover`, which zeroed every generated padding. Nothing
        // said so until a render showed cells with no padding.
        let dir = scratch("vocab-universal");
        write(&dir, "css/styles.css", "* { margin: 0; padding: 0; }\n");
        let err = std::panic::catch_unwind(|| Vocabulary::in_frontend(&dir).run(&Emit::default()))
            .unwrap_err();
        let msg = err
            .downcast_ref::<String>()
            .expect("panic payload is a String");
        assert!(msg.contains("* {"), "got: {msg}");
        assert!(msg.contains("padding"), "got: {msg}");
    }

    #[test]
    fn a_universal_reset_in_a_layer_beneath_makeover_is_not_read() {
        let dir = scratch("vocab-universal-beneath");
        write(
            &dir,
            "css/styles.css",
            "/* { */ @layer reset {\n  * { margin: 0; padding: 0; }\n}\n.x { content: \"}\"; }\n",
        );
        Vocabulary::in_frontend(&dir)
            .beneath(&["reset"])
            .run(&Emit::default());
    }

    #[test]
    fn a_layer_not_named_beneath_is_still_read() {
        let dir = scratch("vocab-universal-other-layer");
        write(
            &dir,
            "css/styles.css",
            "@layer base {\n  * { padding: 0; }\n}\n",
        );
        let err = std::panic::catch_unwind(|| {
            Vocabulary::in_frontend(&dir)
                .beneath(&["reset"])
                .run(&Emit::default());
        })
        .unwrap_err();
        let msg = err.downcast_ref::<String>().expect("a String payload");
        assert!(msg.contains("* {"), "got: {msg}");
    }

    #[test]
    fn a_universal_rule_touching_nothing_generated_is_not_a_clash() {
        let dir = scratch("vocab-universal-box");
        write(&dir, "css/styles.css", "* { box-sizing: border-box; }\n");
        Vocabulary::in_frontend(&dir).run(&Emit::default());
    }

    #[test]
    fn a_handoff_on_the_class_is_the_remedy_and_reads_as_one() {
        let dir = scratch("vocab-element-handoff");
        // What a consumer writes instead of an exception: the element rule
        // stays, and a later layer gives the property back on the class. The
        // check has to read that as settled or the remedy fails the build it
        // was written to fix.
        write(
            &dir,
            "css/styles.css",
            "select { box-shadow: none; }\n.field { box-shadow: revert-layer; }\n",
        );
        Vocabulary::in_frontend(&dir).run(&Emit::default());
    }

    #[test]
    fn a_property_the_app_states_on_the_class_is_not_the_element_rules_doing() {
        let dir = scratch("vocab-element-spoken-for");
        // Within the app's own sheet the class rule outranks the bare element
        // rule, so what reaches the design system is `.button`, not `button`.
        // The class pass has that pair, here as a reviewed one, and
        // reporting it twice would ask for two remedies for one collision.
        write(
            &dir,
            "css/styles.css",
            "select { box-shadow: none; }\n.field { box-shadow: none; }\n",
        );
        Vocabulary::in_frontend(&dir)
            .allow(Allow::class("field", "box-shadow"))
            .run(&Emit::default());
    }

    #[test]
    fn a_handoff_that_loses_to_the_rule_it_remedies_is_not_a_remedy() {
        let dir = scratch("vocab-element-weak-handoff");
        // The shape that reads as fixed and is not: both rules are the app's
        // and both are in the same layer, so the state on the element rule
        // decides, and the described field keeps the app's sunken fill.
        write(
            &dir,
            "css/styles.css",
            "select:focus { box-shadow: none; }\n.field { box-shadow: revert-layer; }\n",
        );
        let err = std::panic::catch_unwind(|| Vocabulary::in_frontend(&dir).run(&Emit::default()))
            .unwrap_err();
        let msg = err
            .downcast_ref::<String>()
            .expect("panic payload is a String");
        assert!(msg.contains(".field"), "got: {msg}");

        // Written to win, it is.
        let dir = scratch("vocab-element-strong-handoff");
        write(
            &dir,
            "css/styles.css",
            "select:focus { box-shadow: none; }\nselect.field { box-shadow: revert-layer; }\n",
        );
        Vocabulary::in_frontend(&dir).run(&Emit::default());
    }

    #[test]
    fn a_scoped_rule_is_not_read_as_an_element_rule() {
        let dir = scratch("vocab-element-scoped");
        // It reaches the buttons inside one region rather than every button, so
        // whether it lands on a described act depends on where that act
        // renders. Failing the build on a guess is the worse error.
        write(
            &dir,
            "css/styles.css",
            ".wizard select { box-shadow: none; }\n",
        );
        Vocabulary::in_frontend(&dir).run(&Emit::default());
    }

    #[test]
    fn an_element_the_design_system_never_renders_onto_is_left_alone() {
        let dir = scratch("vocab-element-unpaired");
        // `.card` is a container: no generated class sits on a `<footer>`, so
        // there is nothing for this rule to take.
        write(&dir, "css/styles.css", "footer { box-shadow: none; }\n");
        Vocabulary::in_frontend(&dir).run(&Emit::default());
    }

    #[test]
    fn a_reviewed_element_pairing_passes_and_stops_passing_when_it_stops_colliding() {
        let dir = scratch("vocab-element-allowed");
        write(&dir, "css/styles.css", "select { box-shadow: none; }\n");
        Vocabulary::in_frontend(&dir)
            .allow(Allow::element("select", "field", "box-shadow"))
            .run(&Emit::default());

        // And the same licence against a sheet that no longer collides fails,
        // for the reason the class list's does.
        let dir = scratch("vocab-element-allowed-stale");
        write(&dir, "css/styles.css", "select { padding: 2px; }\n");
        let err = std::panic::catch_unwind(|| {
            Vocabulary::in_frontend(&dir)
                .allow(Allow::element("select", "field", "box-shadow"))
                .run(&Emit::default());
        })
        .unwrap_err();
        let msg = err
            .downcast_ref::<String>()
            .expect("panic payload is a String");
        assert!(msg.contains("no longer collides"), "got: {msg}");
    }

    /// How many rung classes the vocabulary holds, and on how many ladders.
    fn ladders(names: &std::collections::BTreeSet<String>) -> (usize, usize) {
        let mut rungs = 0;
        let mut ladders = 0;
        for ladder in ["min-", "short-"] {
            let here = names
                .iter()
                .filter(|c| {
                    c.strip_prefix(ladder)
                        .is_some_and(|n| !n.is_empty() && n.bytes().all(|b| b.is_ascii_digit()))
                })
                .count();
            rungs += here;
            ladders += usize::from(here > 0);
        }
        (rungs, ladders)
    }

    #[test]
    fn dead_vocabulary_above_the_seal_fails_and_below_it_passes() {
        let dir = scratch("vocab-seal");
        let opts = Emit::default();
        let names = crate::vocabulary::names(&opts);
        let (rungs, ladders) = ladders(&names);
        assert!(ladders >= 1, "the floor ladder is in the vocabulary");
        // Markup naming nothing: every class is unused, and each ladder counts
        // once rather than once a rung.
        let dead = names.len() - rungs + ladders;
        write(&dir, "index.html", "<div></div>\n");
        let markup = [dir.join("index.html")];

        check_vocabulary_use(&markup, &opts, dead);
        assert!(
            std::panic::catch_unwind(|| check_vocabulary_use(&markup, &opts, dead - 1)).is_err(),
            "a vocabulary deader than the seal has to fail"
        );
    }

    #[test]
    fn one_rung_of_the_floor_ladder_uses_the_ladder() {
        // A column carries whichever rung its floor lands on, so a site naming
        // one rung is using the ladder, and one naming none has one dead name.
        let opts = Emit::default();
        let names = crate::vocabulary::names(&opts);
        let (rungs, ladders) = ladders(&names);
        let dead = names.len() - rungs + ladders;

        let dir = scratch("vocab-ladder");
        write(&dir, "index.html", "<div class=\"cell min-16\"></div>\n");
        let one_rung = [dir.join("index.html")];
        // `cell` is named too, so two fewer than a page naming nothing.
        check_vocabulary_use(&one_rung, &opts, dead - 2);

        // A longer rung does not name a shorter one it starts with.
        write(&dir, "index.html", "<div class=\"min-24\"></div>\n");
        assert!(haystack_names("<div class=\"min-24\">", "min-24"));
        assert!(!haystack_names("<div class=\"min-24\">", "min-2"));
    }

    #[test]
    fn a_class_is_named_whole_on_both_sides() {
        assert!(haystack_names("class=\"row\"", "row"));
        assert!(!haystack_names("class=\"row-flex\"", "row"));
        assert!(!haystack_names("class=\"flex-row\"", "row"));
        assert!(haystack_names("el.classList.add('row')", "row"));
    }

    #[test]
    fn range_syntax_and_units_are_read() {
        assert_eq!(media_widths("(width < 600px)"), [Width::Px(600)]);
        assert_eq!(
            media_widths(" (600px <= width < 840px)"),
            [Width::Px(600), Width::Px(840)]
        );
        assert_eq!(media_widths(" (max-width: 48em)"), [Width::Px(768)]);
        assert_eq!(media_widths(" (min-width: 37.5rem)"), [Width::Px(600)]);
        assert_eq!(
            media_widths(" (max-width: 599.98px)"),
            [Width::Other("599.98px".into())]
        );
        assert_eq!(
            media_widths(" (width < 50vw)"),
            [Width::Other("50vw".into())]
        );
        assert!(media_widths(" (min-height: 600px)").is_empty());
        assert!(media_widths(" (max-device-width: 600px)").is_empty());
        assert!(media_widths(" (hover: hover) and (pointer: fine)").is_empty());
    }

    #[test]
    fn every_size_class_condition_passes_its_own_check() {
        let dir = frontend("bp-classes");
        let mut css = String::new();
        for class in SizeClass::all() {
            let _ = writeln!(css, "@media {} {{ body {{ }} }}", class.media_condition());
        }
        write(&dir, "css/styles.css", &css);
        write(
            &dir,
            "js/shell.js",
            &format!("matchMedia('{}');\n", SizeClass::Compact.media_condition()),
        );
        Breakpoints::in_frontend(&dir).run();
    }

    #[test]
    #[should_panic(expected = "48em")]
    fn a_width_in_em_is_a_width_and_not_a_bare_number() {
        let dir = frontend("bp-em");
        write(&dir, "css/styles.css", "@media (max-width: 48em) { }\n");
        Breakpoints::in_frontend(&dir).tuning(&[48]).run();
    }

    #[test]
    #[should_panic(expected = "(width < 768px)")]
    fn a_stale_range_width_fails() {
        let dir = frontend("bp-range");
        write(&dir, "css/styles.css", "@media (width < 768px) { }\n");
        Breakpoints::in_frontend(&dir).run();
    }

    #[test]
    #[should_panic(expected = "599px")]
    fn the_old_inclusive_compact_bound_is_stale() {
        let dir = frontend("bp-599");
        write(&dir, "css/styles.css", "@media (max-width: 599px) { }\n");
        Breakpoints::in_frontend(&dir).run();
    }

    #[test]
    fn a_call_in_script_is_not_a_feature() {
        assert!(js_widths("const w = Math.max(width, 600);").is_empty());
        assert!(js_widths("el.style.cssText = 'max-width: 320px';").is_empty());
        assert_eq!(js_widths("matchMedia('(width < 600px)')").len(), 1);
    }

    #[test]
    fn a_slash_star_slash_opens_a_comment_rather_than_closing_one() {
        let css = "/*/ @media (max-width: 768px) { } */ a { }";
        let stripped = blank(css, Lang::Css);
        assert!(!stripped.contains("768"), "{stripped:?}");
        assert!(stripped.contains("a { }"));
        assert_eq!(stripped.len(), css.len());
    }

    #[test]
    fn a_comment_opener_inside_a_string_is_text() {
        // Read as a comment, the `/*` would blank the query after it.
        let css = "a::after { content: \"/*\"; }\n@media (max-width: 768px) { }\n";
        let src = blank(css, Lang::Css);
        assert_eq!(media_conditions(&src).len(), 1);
        assert!(src.contains("768"));

        let js = "const glob = '/*';\nmatchMedia('(width < 600px)');\n";
        assert_eq!(js_widths(&blank(js, Lang::Js)).len(), 1);
    }

    #[test]
    fn a_query_in_a_script_comment_is_prose() {
        let js = "// was matchMedia('(width < 768px)')\n/* (max-width: 500px) */\n";
        assert!(js_widths(&blank(js, Lang::Js)).is_empty());
    }

    #[test]
    fn a_brace_inside_a_css_string_does_not_end_a_condition() {
        let css = "@media (width < 600px) { a::after { content: \"{\"; } }";
        let src = blank(css, Lang::Css);
        assert_eq!(media_conditions(&src).len(), 1);
    }

    #[test]
    fn blanking_keeps_byte_offsets_through_multibyte_text() {
        // An em dash in a comment and in a string: three bytes each, blanked
        // to three spaces, so everything after them sits where it did.
        let css = "/* a \u{2014} b */ a::after { content: \"\u{2014}\"; }\n@layer reset { * { padding: 0; } }";
        let src = blank(css, Lang::Css);
        assert_eq!(src.len(), css.len());
        let at = css.find("@layer").unwrap();
        assert_eq!(&src[at..at + 6], "@layer");
        let dropped = drop_layers(css, &["reset"]);
        assert!(!dropped.contains("padding"), "{dropped:?}");
    }

    #[test]
    fn blanking_keeps_lines_and_offsets() {
        let css = "/* one\ntwo */\n\"x\ny\"\n@media (max-width: 1px) {}";
        let src = blank(css, Lang::Css);
        assert_eq!(src.len(), css.len());
        assert_eq!(src.lines().count(), css.lines().count());
    }

    #[test]
    fn both_quote_styles_read() {
        let want = Density::Touch.media_condition();
        for q in ['\'', '"'] {
            let src = format!("const {CONST_NAME} = {q}{want}{q};\n");
            let found = touch_density_literals(&src);
            assert_eq!(found.len(), 1);
            assert_eq!(found[0].1, want);
        }
    }

    #[test]
    fn a_file_list_skips_the_sheets_named_generated() {
        let dir = frontend("vocab-files");
        write(&dir, "css/layout.css", ".card { box-shadow: none; }\n");
        write(&dir, "css/app.css", "body { color: red; }\n");
        let files = [dir.join("css/layout.css"), dir.join("css/app.css")];
        Vocabulary::files(&files)
            .generated(&["layout.css"])
            .run(&Emit::default());
        let err = std::panic::catch_unwind(|| Vocabulary::files(&files).run(&Emit::default()))
            .unwrap_err();
        let msg = err.downcast_ref::<String>().cloned().unwrap_or_default();
        assert!(msg.contains("box-shadow"), "got: {msg}");
    }
}