makeover_webview/

vocabulary.rs

//! Every class this crate is responsible for, as a set rather than one name at
//! a time.
//!
//! The naming functions ([`crate::class`], [`crate::option_class`],
//! [`crate::list::part_class`], [`crate::list::cell_part_class`]) answer "what
//! is this one thing called". That is half the agreement, and 0.27.0 shipped
//! it. The other half is the set: a checker cannot ask "is this app rule
//! re-specifying something makeover already defines" without the list, and this
//! crate is the only place that knows it, because this crate writes the sheet.
//!
//! # Two sets, because there are two questions
//!
//! [`vocabulary`] is the classes the generated stylesheet writes a rule for.
//! That is the set a drift check wants: an app rule for one of these is a
//! restatement of a rule the app already gets, and unlayered app CSS beats
//! `@layer makeover`, so the restatement silently wins.
//!
//! [`names`] is every class this crate can put in markup, which is the first
//! set plus the ones it deliberately leaves unruled. `row-actions`,
//! `cell-actions`, `cell-tokens` and `cell-link` have no rule on purpose: only
//! `.cell-value` takes a colour, because a token carries its own tone and an
//! action is a control rather than text. A class that sets no properties is a
//! class that means "I thought about this", and this crate does not emit those.
//! So a screen renderer legitimately emits names that [`vocabulary`] does not
//! contain, and a test asking "is every class this renderer emits one makeover
//! knows about" has to read [`names`] or it fails on four correct ones.
//!
//! # Why the first set is scraped and not listed
//!
//! A hand-maintained copy of the sheet's contents is the defect being fixed,
//! one level up: it can disagree with the sheet, and the day it does, the
//! checker reads the list and the browser reads the sheet. So [`vocabulary`]
//! parses the CSS this crate generates. There is no second source to drift
//! from, and a class added to an emitter enters the vocabulary in the same
//! commit that adds it.

use crate::list::{CELL_PART_CLASSES, FLOW_CLASSES, ROW_PART_CLASSES};
use crate::{Emit, option_class};
use makeover_layout::Selector;
use std::collections::{BTreeMap, BTreeSet};

/// Every class name the generated stylesheet defines a rule for, prefixed the
/// way `opts` prefixes them.
///
/// Includes the state classes a caller never spells alone (`chosen`,
/// `latched`). Those are deliberately unprefixed: they qualify a prefixed
/// component (`.mo-tab.chosen`) rather than standing on their own, so a prefix
/// moves the thing and not its state.
#[must_use]
pub fn vocabulary(opts: &Emit) -> BTreeSet<String> {
    classes_in_css(&crate::stylesheet(opts))
}

/// Every class this crate can put in markup or in a rule.
///
/// [`vocabulary`] plus the part classes it deliberately leaves unruled. This is
/// the set to check a renderer's emitted markup against: a class outside it is
/// a name that renderer invented, which is how quasi-webview came to spell
/// `tabs`, `segmented` and `option` and render every described selector flat.
#[must_use]
pub fn names(opts: &Emit) -> BTreeSet<String> {
    let mut all = vocabulary(opts);
    all.extend(
        ROW_PART_CLASSES
            .iter()
            .chain(CELL_PART_CLASSES)
            .chain(FLOW_CLASSES)
            .chain(crate::RUN_CLASSES)
            .map(|name| crate::class(name, opts)),
    );
    all.extend(
        [Selector::Tabs, Selector::Segmented, Selector::Toggle]
            .into_iter()
            .map(|s| crate::class(option_class(s), opts)),
    );
    all
}

/// Which properties a stylesheet sets on each class it names.
///
/// The grain a drift check actually wants. A class name in common is not by
/// itself a divergence: goingson's `.badge` sets shape and the generated
/// `.badge` sets fill and edge, and the app's own comment says "do not add
/// background, border or box-shadow here". That arrangement is settled and
/// correct, so a check that flagged the shared name would demand deleting it.
/// A shared *property* is the thing that goes wrong, because app CSS is
/// unlayered and takes the property from the design system silently.
///
/// A property appearing under more than one selector arm collapses into one
/// entry. That loses a real distinction -- the sort caret's reserved gap is
/// `content` on the unsorted arm and the generated caret is `content` on the
/// sorted one, which is a deliberate pairing rather than a clash -- so a
/// consumer of this needs a way to say a pair was reviewed. Deciding that here
/// would need a selector matcher, and a check that guesses wrong about
/// specificity fails correct builds.
///
/// A declaration whose value is exactly `revert-layer` is not one of them. It
/// takes nothing by construction: it is a later layer handing the property back
/// to the one below, which is the opposite of the thing this reader is looking
/// for. Counting it made every handoff in a consumer's sheet look like an
/// override, and the allowlist entry written to silence one went on permitting
/// a real override on the same pair afterwards. [`deferrals_by_class`] is where
/// those declarations go instead.
#[must_use]
pub fn declarations_by_class(css: &str) -> BTreeMap<String, BTreeSet<String>> {
    by_class(css, |value| !is_handoff(value))
}

/// Which properties a stylesheet hands back to the layer below, per class.
///
/// The other half of [`declarations_by_class`]. A `revert-layer` says "whatever
/// the design system set here, keep it", so a checker reading a consumer's
/// sheet wants it as evidence that a clash was already remedied rather than as
/// a clash of its own.
#[must_use]
pub fn deferrals_by_class(css: &str) -> BTreeMap<String, BTreeSet<String>> {
    by_class(css, is_handoff)
}

/// [`declarations_by_class`] and [`deferrals_by_class`], which differ only in
/// which declarations they keep.
fn by_class(css: &str, keep: impl Fn(&str) -> bool) -> BTreeMap<String, BTreeSet<String>> {
    let mut out: BTreeMap<String, BTreeSet<String>> = BTreeMap::new();
    for (selector, body) in rules(css) {
        let classes = classes_in_selector(&selector);
        if classes.is_empty() {
            continue;
        }
        let properties = properties_in_body(&body, &keep);
        if properties.is_empty() {
            continue;
        }
        for class in classes {
            out.entry(class).or_default().extend(properties.clone());
        }
    }
    out
}

/// Which properties a stylesheet sets on each bare element it names.
///
/// The blind spot [`declarations_by_class`] has by construction: it keys rules
/// by the classes in their selectors, so a rule carrying no class at all is
/// invisible to it. `button { color: var(--content) }` is exactly that, and it
/// sets the same property the generated `.button` does on every described act
/// in the app -- including the tone of a destructive one, which is how a delete
/// came to look like an ordinary button for months with the check reporting
/// nothing.
///
/// Only a selector arm that is one bare compound counts: `button`,
/// `button:hover`, `input[type="text"]`. A scoped arm (`.page button`) 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 is rendered, and a check
/// that guessed would fail correct builds. The certain case is the one this
/// reads.
///
/// Pair the result against [`classes_for_element`] to ask the question a
/// checker wants: does this element rule take a property the design system sets
/// on a class that element can carry.
///
/// The answer carries the strongest arm each property was set on, because the
/// app's own remedy has to outrank the rule it remedies. `.field` does not beat
/// `input[type="text"]`: both are the app's, both are in the same layer, and
/// the attribute makes the element rule the more specific of the two. A check
/// reading only "the app mentions this pair somewhere" waves that straight
/// through, which is the shape of every handoff that looked written and was
/// not.
#[must_use]
pub fn declarations_by_element(css: &str) -> BTreeMap<String, BTreeMap<String, Specificity>> {
    let mut out: BTreeMap<String, BTreeMap<String, Specificity>> = BTreeMap::new();
    for (selector, body) in rules(css) {
        let properties = properties_in_body(&body, |value| !is_handoff(value));
        if properties.is_empty() {
            continue;
        }
        for arm in selector.split(',') {
            let Some(element) = bare_element(arm) else {
                continue;
            };
            let rank = specificity(arm);
            let entry = out.entry(element).or_default();
            for property in &properties {
                let strongest = entry.entry(property.clone()).or_default();
                *strongest = (*strongest).max(rank);
            }
        }
    }
    out
}

/// What a stylesheet says about each class, and how strongly.
///
/// Every property the sheet names on a class, whether it takes it or hands it
/// back, keyed by the strongest arm that names it. The question it answers is
/// not "does this collide" -- [`declarations_by_class`] is that -- but "has the
/// app spoken for this pair, in a rule that wins where it has to".
#[must_use]
pub fn mentions_by_class(css: &str) -> BTreeMap<String, BTreeMap<String, Specificity>> {
    let mut out: BTreeMap<String, BTreeMap<String, Specificity>> = BTreeMap::new();
    for (selector, body) in rules(css) {
        let properties = properties_in_body(&body, |_| true);
        if properties.is_empty() {
            continue;
        }
        for arm in selector.split(',') {
            let classes = classes_in_selector(arm);
            if classes.is_empty() {
                continue;
            }
            let rank = specificity(arm);
            for class in classes {
                let entry = out.entry(class).or_default();
                for property in &properties {
                    let strongest = entry.entry(property.clone()).or_default();
                    *strongest = (*strongest).max(rank);
                }
            }
        }
    }
    out
}

/// How CSS ranks one selector: ids, then classes, then elements.
///
/// Ordered the way the cascade orders it, so the tuple comparison is the
/// cascade's comparison. It settles a contest between two rules in the same
/// layer, which is the only contest it is used for here: a layer beats
/// specificity outright, so nothing in the app's sheet has to be compared
/// against the generated one this way.
pub type Specificity = (usize, usize, usize);

/// The specificity of one selector arm.
///
/// A functional pseudo-class counts as one class and its argument is not read.
/// CSS says `:not(.a.b)` takes the specificity of its strongest argument, so
/// this undercounts a compound inside one -- which puts the error on the side
/// of reporting a remedy as too weak rather than accepting one that is.
#[must_use]
pub fn specificity(selector: &str) -> Specificity {
    let chars: Vec<char> = selector.chars().collect();
    let (mut ids, mut classes, mut elements) = (0, 0, 0);
    let mut i = 0;
    while i < chars.len() {
        match chars[i] {
            '#' => {
                ids += 1;
                i = skip_name(&chars, i + 1);
            }
            '.' => {
                classes += 1;
                i = skip_name(&chars, i + 1);
            }
            ':' => {
                // `::before` is an element, `:hover` is a class.
                if chars.get(i + 1) == Some(&':') {
                    elements += 1;
                    i = skip_name(&chars, i + 2);
                } else {
                    classes += 1;
                    i = skip_name(&chars, i + 1);
                }
                if chars.get(i) == Some(&'(') {
                    i = skip_group(&chars, i);
                }
            }
            '[' => {
                classes += 1;
                i = skip_group(&chars, i);
            }
            c if c.is_ascii_alphabetic() => {
                elements += 1;
                i = skip_name(&chars, i);
            }
            // A combinator, whitespace, or the universal selector, none of
            // which count for anything.
            _ => i += 1,
        }
    }
    (ids, classes, elements)
}

/// Past the identifier starting at `from`.
fn skip_name(chars: &[char], from: usize) -> usize {
    let mut i = from;
    while i < chars.len() && (chars[i].is_alphanumeric() || chars[i] == '-' || chars[i] == '_') {
        i += 1;
    }
    i
}

/// Past the bracketed or parenthesised group opening at `from`, nesting and
/// all.
fn skip_group(chars: &[char], from: usize) -> usize {
    let mut depth = 0usize;
    let mut i = from;
    while i < chars.len() {
        match chars[i] {
            '[' | '(' => depth += 1,
            ']' | ')' => {
                depth -= 1;
                if depth == 0 {
                    return i + 1;
                }
            }
            _ => {}
        }
        i += 1;
    }
    i
}

/// A value that hands the property back rather than taking it.
///
/// Bare only. `revert-layer !important` in a later layer inverts layer order
/// and takes the property from every layer below, which is the opposite
/// declaration wearing the same word.
fn is_handoff(value: &str) -> bool {
    value.trim() == "revert-layer"
}

/// The property names a declaration block sets, keeping the ones `keep` admits.
fn properties_in_body(body: &str, keep: impl Fn(&str) -> bool) -> BTreeSet<String> {
    body.split(';')
        .filter_map(|decl| decl.split_once(':'))
        .filter(|(_, value)| keep(value))
        .map(|(name, _)| name.trim().to_string())
        .filter(|name| !name.is_empty() && !name.contains(['{', '}']))
        .collect()
}

#[must_use]
pub fn classes_in_css(css: &str) -> BTreeSet<String> {
    rules(css)
        .into_iter()
        .flat_map(|(selector, _)| classes_in_selector(&selector))
        .collect()
}

/// `(selector, declaration block)` for every rule in a stylesheet.
///
/// One reader for both sides. Comparing what makeover defines against what an
/// app defines is only meaningful if the two were read the same way, which is
/// why this is the only place either question is answered from.
///
/// A comment is skipped whole: the banner at the top of the generated sheet is
/// prose about the cascade layer and would otherwise contribute words that look
/// like selectors. A string is opaque, because `content: "\25B2"` is the sort
/// caret rather than a selector and a brace inside one would desync the stack.
/// An at-rule block (`@layer`, `@media`, `@supports`) holds rules rather than
/// declarations, so a depth counter alone is not enough and the stack records
/// what kind of block each brace opened.
fn rules(css: &str) -> Vec<(String, String)> {
    let mut out = Vec::new();
    // One entry per open brace: true when that block holds declarations rather
    // than nested rules.
    let mut blocks: Vec<bool> = Vec::new();
    // Text since the last `{`, `}` or `;`. What precedes a `{` is that block's
    // prelude, and a prelude starting with `@` opens an at-rule.
    let mut prelude = String::new();
    // The selector of each open declaration block, and the body so far.
    let mut open: Vec<(String, String)> = Vec::new();

    let mut chars = css.chars().peekable();
    while let Some(c) = chars.next() {
        match c {
            '/' if chars.peek() == Some(&'*') => {
                chars.next();
                let mut star = false;
                for c in chars.by_ref() {
                    if star && c == '/' {
                        break;
                    }
                    star = c == '*';
                }
                prelude.clear();
            }
            '"' | '\'' => {
                let quote = c;
                let mut escaped = false;
                // Keep the quotes in the body: a value is not a property name,
                // and dropping them would join two declarations into one.
                if blocks.last().copied().unwrap_or(false)
                    && let Some((_, body)) = open.last_mut()
                {
                    body.push(quote);
                }
                for c in chars.by_ref() {
                    if escaped {
                        escaped = false;
                    } else if c == '\\' {
                        escaped = true;
                    } else if c == quote {
                        break;
                    }
                }
                // The closing quote only. A value holding `;` or `:` would
                // otherwise read as two declarations, and `url("a;b:c")` is a
                // real thing an app writes.
                if blocks.last().copied().unwrap_or(false)
                    && let Some((_, body)) = open.last_mut()
                {
                    body.push(quote);
                }
            }
            '{' => {
                let declarations = !prelude.trim_start().starts_with('@');
                if declarations {
                    open.push((prelude.clone(), String::new()));
                }
                blocks.push(declarations);
                prelude.clear();
            }
            '}' => {
                if blocks.pop().unwrap_or(false)
                    && let Some(rule) = open.pop()
                {
                    out.push(rule);
                }
                prelude.clear();
            }
            _ => {
                if blocks.last().copied().unwrap_or(false)
                    && let Some((_, body)) = open.last_mut()
                {
                    body.push(c);
                } else if c == ';' {
                    prelude.clear();
                } else {
                    prelude.push(c);
                }
            }
        }
    }
    out
}

/// Which generated classes each element can plausibly carry.
///
/// The half of the element check that CSS cannot answer. A stylesheet says
/// `button { color: ... }` and `.chip { color: ... }` and nothing in either
/// text says a chip is rendered as a `<button>`; the renderer knows that, and
/// this crate is the renderer. So the pairing is declared here rather than
/// inferred, and [`declarations_by_element`] supplies the other half.
///
/// Read it as "may carry", not "does carry". A pairing that never occurs in a
/// given app costs a check that finds nothing; a pairing left out is a defect
/// that ships, which is the trade this list is written on the generous side
/// of.
///
/// `div` and `span` are deliberately absent. Nearly every container class in
/// the vocabulary sits on one of them, so the pairing would be the whole
/// vocabulary against one rule and would say nothing about which class was
/// meant. An app writing a bare `div { }` rule has a wider problem than this
/// check, and the classes it would clobber are containers rather than the
/// controls whose tone and bevel carry meaning.
pub const ELEMENT_CLASSES: &[(&str, &[&str])] = &[
    // The controls. `a` and `button` are interchangeable in markup for most of
    // these -- a link that posts is a button, an act that navigates is an
    // anchor -- which is why the two lists overlap as much as they do.
    (
        "a",
        &[
            "link",
            "button",
            "tab",
            "chip",
            "badge",
            "card",
            "row-activate",
            "figure-act",
            "chrome-place",
        ],
    ),
    (
        "button",
        &[
            "button",
            "chip",
            "segment",
            "toggle",
            "tab",
            "link",
            "badge",
            "card",
            "facet-take",
            "facet-prune",
            "chip-remove",
            "row-activate",
        ],
    ),
    // A disclosure. quasi-webview renders an ask as `<details>` with a
    // `<summary>` that is styled as an act.
    ("details", &["ask"]),
    ("summary", &["button", "ask-open", "ask-body"]),
    // The form controls. `.field` is the well every one of them sits in.
    ("input", &["field", "toggle", "row-select"]),
    ("select", &["field"]),
    ("textarea", &["field"]),
    (
        "label",
        &[
            "form-label",
            "form-checkbox-label",
            "form-radio-label",
            "toggle",
        ],
    ),
    ("form", &["form"]),
    ("progress", &["progress"]),
    // Text and lists.
    ("p", &["text", "facet-name", "placeholder-text"]),
    ("ul", &["list", "facet-values"]),
    ("ol", &["list"]),
    ("li", &["facet-value"]),
    // A table written in HTML rather than described. quasi-webview renders a
    // described table as divs carrying the same classes, so both spellings of
    // the same table answer to the same rules and both are worth checking.
    ("table", &["table"]),
    ("thead", &["table-head"]),
    ("tr", &["table-row"]),
    ("td", &["cell", "cell-value", "cell-content"]),
    ("th", &["table-heading"]),
    // A figure, likewise: the described picture is divs, the hand-written one
    // is the HTML element that means the same thing.
    ("figure", &["picture", "figure"]),
    ("img", &["picture-img"]),
    ("figcaption", &["picture-caption", "figure-caption"]),
    ("nav", &["chrome-nav"]),
];

/// The generated classes `element` can carry, prefixed the way `opts` prefixes
/// them.
///
/// Empty for an element the design system never renders onto, which is the
/// answer for most of them: a rule on one of those cannot collide with a
/// generated class because no generated class is ever on it.
#[must_use]
pub fn classes_for_element(element: &str, opts: &Emit) -> BTreeSet<String> {
    ELEMENT_CLASSES
        .iter()
        .find(|(name, _)| *name == element)
        .map(|(_, classes)| classes.iter().map(|c| crate::class(c, opts)).collect())
        .unwrap_or_default()
}

/// The element name of one bare compound arm, if that is what it is.
fn bare_element(arm: &str) -> Option<String> {
    // An attribute value or a `:not()` argument can hold anything, including
    // the spaces and dots this then rejects on. Neither changes which element
    // the arm styles, so both go before the test rather than into it.
    let mut flat = String::with_capacity(arm.len());
    let mut depth = 0usize;
    for c in arm.chars() {
        match c {
            '[' | '(' => depth += 1,
            ']' | ')' => depth = depth.saturating_sub(1),
            _ if depth == 0 => flat.push(c),
            _ => {}
        }
    }
    let flat = flat.trim();
    // A descendant, a child, a class, an id or a universal: not this.
    if flat.is_empty() || flat.contains(['.', '#', '>', '+', '~', '*']) {
        return None;
    }
    if flat.chars().any(char::is_whitespace) {
        return None;
    }
    let name: String = flat
        .chars()
        .take_while(|c| c.is_alphanumeric() || *c == '-')
        .collect();
    // A pseudo-element on nothing (`::selection`) or a pseudo-class on nothing
    // (`:root`) names no element.
    if !name.starts_with(|c: char| c.is_ascii_alphabetic()) {
        return None;
    }
    Some(name.to_ascii_lowercase())
}

/// The class names one selector matches on.
fn classes_in_selector(selector: &str) -> Vec<String> {
    let chars: Vec<char> = selector.chars().collect();
    let mut names = Vec::new();
    let mut i = 0;
    while i < chars.len() {
        // A leading digit is a length (`.5rem`), never a class: CSS forbids an
        // identifier starting with one.
        if chars[i] == '.'
            && chars
                .get(i + 1)
                .is_some_and(|c| c.is_alphabetic() || *c == '_')
        {
            let start = i + 1;
            let mut end = start;
            while end < chars.len()
                && (chars[end].is_alphanumeric() || chars[end] == '-' || chars[end] == '_')
            {
                end += 1;
            }
            names.push(chars[start..end].iter().collect());
            i = end;
        } else {
            i += 1;
        }
    }
    names
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::list::{cell_part_class, part_class};
    use makeover_layout::{CellPart, RowPart};

    #[test]
    fn the_scrape_finds_the_components_the_sheet_is_built_from() {
        let v = vocabulary(&Emit::default());
        assert!(
            v.len() > 20,
            "scraped {} classes, which reads as a parser failure rather than a small sheet",
            v.len()
        );
        for name in ["card", "tab", "table-heading", "cell-value", "chosen"] {
            assert!(
                v.contains(name),
                "the sheet defines .{name} and the scan missed it"
            );
        }
    }

    #[test]
    fn every_name_a_caller_can_ask_for_is_one_this_crate_admits_to() {
        // The two halves of the agreement, checked against each other. A naming
        // function returning a class outside `names` would put a class in the
        // markup that nothing downstream can recognise, which is the failure
        // quasi-webview shipped and phase 1 exists to make impossible.
        let opts = Emit::default();
        let all = names(&opts);

        for selector in [Selector::Tabs, Selector::Segmented, Selector::Toggle] {
            let name = option_class(selector);
            assert!(
                all.contains(name),
                "option_class({selector:?}) is .{name}, which nothing admits to"
            );
        }
        for part in [
            RowPart::Primary,
            RowPart::Secondary,
            RowPart::Meta,
            RowPart::Actions,
            RowPart::Tokens,
            RowPart::Proportion,
        ] {
            let name = part_class(part);
            assert!(
                all.contains(name),
                "part_class({part:?}) is .{name}, which nothing admits to"
            );
        }
        for part in [
            CellPart::Value,
            CellPart::Tokens,
            CellPart::Actions,
            CellPart::Link,
        ] {
            let name = cell_part_class(part);
            assert!(
                all.contains(name),
                "cell_part_class({part:?}) is .{name}, which nothing admits to"
            );
        }
    }

    #[test]
    fn the_part_lists_hold_every_arm_of_the_match_beside_them() {
        // ROW_PART_CLASSES and CELL_PART_CLASSES are written out because a
        // `#[non_exhaustive]` enum cannot be enumerated. This is the test that
        // stops them drifting from the matches they sit next to.
        for part in [
            RowPart::Primary,
            RowPart::Secondary,
            RowPart::Meta,
            RowPart::Actions,
            RowPart::Tokens,
            RowPart::Proportion,
        ] {
            assert!(
                ROW_PART_CLASSES.contains(&part_class(part)),
                "{part:?} is missing from ROW_PART_CLASSES"
            );
        }
        for part in [
            CellPart::Value,
            CellPart::Tokens,
            CellPart::Actions,
            CellPart::Link,
        ] {
            assert!(
                CELL_PART_CLASSES.contains(&cell_part_class(part)),
                "{part:?} is missing from CELL_PART_CLASSES"
            );
        }
        // The fallbacks, which are what an upstream addition lands on.
        assert!(ROW_PART_CLASSES.contains(&"row-part"));
        assert!(CELL_PART_CLASSES.contains(&"cell-part"));
    }

    #[test]
    fn a_prefix_moves_the_component_classes_and_leaves_the_states_qualifying_them() {
        let plain = vocabulary(&Emit::default());
        let prefixed = vocabulary(&Emit {
            class_prefix: "mo-",
            ..Emit::default()
        });
        assert_eq!(
            plain.len(),
            prefixed.len(),
            "a prefix changed how many classes exist"
        );
        // `chosen` and `latched` never stand alone: the sheet writes
        // `.mo-tab.chosen`, so the state stays bare while the thing moves.
        // `current` is the third, and it is the same shape: which child of a
        // region showing one at a time is the one showing.
        let states = ["chosen", "latched", "current"];
        for name in &plain {
            let expected = if states.contains(&name.as_str()) {
                name.clone()
            } else {
                format!("mo-{name}")
            };
            assert!(
                prefixed.contains(&expected),
                ".{name} did not move to .{expected} under the prefix"
            );
        }
    }

    #[test]
    fn a_handoff_is_not_an_override() {
        // The defect this split fixes. `revert-layer` in a later layer gives
        // the property back to the design system, so counting it as a taking
        // made every remedy in a consumer's sheet read as the thing it
        // remedied -- and the allowlist entry written to silence one went on
        // permitting a real override on the same pair for good.
        let css = ".button { background: revert-layer; color: red; }";
        let taken = declarations_by_class(css);
        let given = deferrals_by_class(css);
        assert_eq!(
            taken.get("button"),
            Some(&["color".to_string()].into_iter().collect())
        );
        assert_eq!(
            given.get("button"),
            Some(&["background".to_string()].into_iter().collect())
        );
    }

    #[test]
    fn an_important_handoff_is_an_override() {
        // `revert-layer !important` in a later layer inverts layer order and
        // takes the property from every layer below it. Same word, opposite
        // declaration, and the one shape of it this reader must not wave
        // through.
        let css = ".button { background: revert-layer !important; }";
        assert_eq!(
            declarations_by_class(css).get("button"),
            Some(&["background".to_string()].into_iter().collect())
        );
        assert!(!deferrals_by_class(css).contains_key("button"));
    }

    #[test]
    fn a_class_that_only_hands_properties_back_is_not_in_the_taking_set() {
        // An empty entry would read as "this class collides on nothing", which
        // is true, and as "this class is in the map", which is what a caller
        // iterating the map would act on.
        let by_class = declarations_by_class(".field { background: revert-layer; }");
        assert!(!by_class.contains_key("field"), "got {by_class:?}");
    }

    #[test]
    fn an_element_rule_is_read_where_a_class_reader_sees_nothing() {
        let css = "button { color: red; background: blue; }";
        assert!(declarations_by_class(css).is_empty());
        let by_element = declarations_by_element(css);
        let button = by_element.get("button").expect("button is named");
        assert_eq!(
            button.keys().cloned().collect::<Vec<_>>(),
            ["background", "color"]
        );
        // One element, nothing else: (0, 0, 1).
        assert_eq!(button["color"], (0, 0, 1));
    }

    #[test]
    fn the_strongest_arm_is_the_one_reported() {
        // A remedy has to outrank the rule it remedies, so a reader that kept
        // the weakest arm would call a losing handoff sufficient.
        let css = "input { color: red; }\ninput[type=\"text\"]:focus { color: blue; }\n";
        assert_eq!(declarations_by_element(css)["input"]["color"], (0, 2, 1));
    }

    #[test]
    fn a_selector_is_ranked_the_way_the_cascade_ranks_it() {
        for (selector, expected) in [
            ("button", (0, 0, 1)),
            ("*", (0, 0, 0)),
            (".field", (0, 1, 0)),
            ("input.field", (0, 1, 1)),
            ("input[type=\"text\"]", (0, 1, 1)),
            ("button:hover", (0, 1, 1)),
            ("button::before", (0, 0, 2)),
            ("#main .card > button:focus-visible", (1, 2, 1)),
            (".chip.latched[aria-pressed=\"true\"]", (0, 3, 0)),
            ("button:not(.link)", (0, 1, 1)),
        ] {
            assert_eq!(specificity(selector), expected, "{selector}");
        }
    }

    #[test]
    fn what_a_class_is_spoken_for_by_counts_a_handoff_as_speech() {
        // A handoff takes nothing, so `declarations_by_class` is right to drop
        // it -- and it is still the app saying what happens to that property on
        // that class, which is what this reader is for.
        let css = ".field { background: revert-layer; }\ninput.field:focus { color: red; }\n";
        let mentions = mentions_by_class(css);
        assert_eq!(mentions["field"]["background"], (0, 1, 0));
        assert_eq!(mentions["field"]["color"], (0, 2, 1));
    }

    #[test]
    fn only_a_bare_compound_counts_as_an_element_rule() {
        // Each of these styles a `button` and none of them is the certain
        // case. A scoped arm reaches one region, and an arm carrying a class
        // is the class reader's business, not this one's.
        for selector in [
            ".page button",
            "button.link",
            ".card > button",
            "button + button",
            "* button",
        ] {
            let css = format!("{selector} {{ color: red; }}");
            assert!(
                declarations_by_element(&css).is_empty(),
                "{selector} was read as a bare element rule"
            );
        }
    }

    #[test]
    fn a_state_or_an_attribute_does_not_stop_an_arm_being_bare() {
        // All of these reach every button in the document, which is what makes
        // them certain to reach a described one.
        for selector in [
            "button:hover",
            "button:focus-visible",
            "button:disabled",
            "button[aria-disabled=\"true\"]",
            "button:not(.link)",
            "button[data-tone=\"danger\"]:hover",
        ] {
            let css = format!("{selector} {{ color: red; }}");
            assert!(
                declarations_by_element(&css).contains_key("button"),
                "{selector} was not read as a bare element rule"
            );
        }
    }

    #[test]
    fn a_pseudo_element_on_nothing_names_no_element() {
        for selector in [":root", "::selection", "::backdrop", ":root:not(.x)"] {
            let css = format!("{selector} {{ color: red; }}");
            assert!(
                declarations_by_element(&css).is_empty(),
                "{selector} named an element"
            );
        }
    }

    #[test]
    fn every_arm_of_a_list_is_read_on_its_own() {
        let css = "input, select, .field, .page textarea { color: red; }";
        let by_element = declarations_by_element(css);
        assert!(by_element.contains_key("input"));
        assert!(by_element.contains_key("select"));
        assert!(!by_element.contains_key("textarea"), "that arm is scoped");
        assert_eq!(by_element.len(), 2);
    }

    #[test]
    fn an_element_handing_a_property_back_is_not_taking_it() {
        let css = "button { background: revert-layer; }";
        assert!(declarations_by_element(css).is_empty());
    }

    #[test]
    fn the_pairing_map_carries_the_elements_this_crate_renders_onto() {
        // The map is hand-written and the emitters are not, so this is what
        // stops the two drifting. Every `<tag class="...">` in this crate's own
        // source, for a tag the map claims to cover, has to be a pairing the
        // map declares -- or the check reads a smaller world than the renderer
        // writes and the gap is silent.
        let mut checked = 0;
        for (tag, class) in emitted_pairs() {
            if !ELEMENT_CLASSES.iter().any(|(name, _)| *name == tag) {
                continue;
            }
            checked += 1;
            assert!(
                classes_for_element(&tag, &Emit::default()).contains(&class),
                "this crate emits <{tag} class=\"{class}\"> and ELEMENT_CLASSES \
                 does not pair them"
            );
        }
        assert!(
            checked > 5,
            "scraped {checked} pairings off the emitters, which reads as the scan \
             having stopped matching rather than the renderer having shrunk"
        );
    }

    /// `(element, class)` for every literal `<tag class="...">` this crate's
    /// own source emits.
    ///
    /// Source rather than rendered markup, because an emitter no test happens
    /// to call is exactly the one whose pairing nobody wrote down. A class
    /// built at runtime (an option class, a row part) is not a literal and is
    /// not seen here; those are declared in the map by hand.
    fn emitted_pairs() -> Vec<(String, String)> {
        const OPEN: &str = "class=\\\"";
        let mut out = Vec::new();
        for file in std::fs::read_dir("src").expect("read src") {
            let path = file.expect("dir entry").path();
            if path.extension().is_none_or(|e| e != "rs") {
                continue;
            }
            let src = std::fs::read_to_string(&path).expect("read source");
            for (at, _) in src.match_indices(OPEN) {
                // The tag is the last `<name` before the attribute.
                let Some(open) = src[..at].rfind('<') else {
                    continue;
                };
                let tag: String = src[open + 1..]
                    .chars()
                    .take_while(|c| c.is_ascii_alphanumeric() || *c == '-')
                    .collect();
                if tag.is_empty() {
                    continue;
                }
                // What is pushed next: `push_class(out, "name", opts)`.
                let tail = &src[at..(at + 300).min(src.len())];
                let Some(call) = tail.find("push_class(out, \"") else {
                    continue;
                };
                let name: String = tail[call + "push_class(out, \"".len()..]
                    .chars()
                    .take_while(|c| *c != '"')
                    .collect();
                if !name.is_empty() {
                    out.push((tag, name));
                }
            }
        }
        out
    }

    #[test]
    fn the_properties_a_class_carries_are_read_per_class() {
        let css = ".badge { padding: 1px; font-weight: 600; }\n                   .badge[data-color] { border: 1px solid red; }\n                   @media (min-width: 40rem) { .badge { padding: 2px; } }\n";
        let by_class = declarations_by_class(css);
        let badge = by_class.get("badge").expect("badge is named");
        // Every arm collapses into one entry, including the one inside the
        // media block: they are all the same class carrying the same property.
        assert!(badge.contains("padding"));
        assert!(badge.contains("font-weight"));
        assert!(badge.contains("border"));
        assert_eq!(badge.len(), 3);
    }

    #[test]
    fn a_value_holding_a_colon_or_a_semicolon_is_not_read_as_a_property() {
        let css = ".x { background: url(\"a;b:c\"); color: red; }";
        let by_class = declarations_by_class(css);
        let x = by_class.get("x").expect("x is named");
        assert_eq!(
            *x,
            ["background".to_string(), "color".to_string()]
                .into_iter()
                .collect::<BTreeSet<_>>()
        );
    }

    #[test]
    fn the_generated_sheet_sets_fill_on_a_badge_and_not_its_shape() {
        // The fact goingson's stylesheet states in prose next to its own
        // `.badge`: "Fill, edge and text colour come from the generated .badge
        // in layout.css... Do not add background, border or box-shadow here."
        // A property-grain reader is what turns that comment into a check.
        let by_class = declarations_by_class(&crate::stylesheet(&Emit::default()));
        let badge = by_class.get("badge").expect("the sheet defines .badge");
        // Token::Badge is Depth::Flat, so a badge carries no bevel and no
        // fill: what the generated sheet gives it is the text colour, and
        // everything about its shape is the app's.
        assert!(badge.contains("color"), "got {badge:?}");
        assert!(
            !badge.contains("padding"),
            "shape is the app's, got {badge:?}"
        );
    }

    #[test]
    fn a_declaration_value_holding_a_dot_is_not_read_as_a_class() {
        let found = classes_in_css(".real { transition: .2s ease; margin: 0.5rem; }");
        assert_eq!(found, ["real".to_string()].into_iter().collect());
    }

    #[test]
    fn an_at_rule_does_not_hide_the_selectors_inside_it() {
        let found = classes_in_css(
            "@layer makeover { @media (min-width: 40rem) { .wide { color: red; } } }",
        );
        assert_eq!(found, ["wide".to_string()].into_iter().collect());
    }

    #[test]
    fn a_string_is_opaque_and_a_comment_contributes_nothing() {
        let found = classes_in_css("/* .notaclass */ .caret::after { content: \"} .alsonot\"; }");
        assert_eq!(found, ["caret".to_string()].into_iter().collect());
    }

    #[test]
    fn a_compound_selector_yields_every_class_it_names() {
        let found = classes_in_css(
            ".tab.chosen[aria-sort=\"ascending\"] > .label:not(.muted) { color: red; }",
        );
        let expected: BTreeSet<String> = ["tab", "chosen", "label", "muted"]
            .into_iter()
            .map(String::from)
            .collect();
        assert_eq!(found, expected);
    }
}