badness_parser/

directives.rs

//! Comment directives that turn badness off for part of a file.
//!
//! Three families, all spelled as ordinary LaTeX line comments. The **verb
//! carries the scope**, so every form reads as an imperative (`skip-file` is
//! "skip this file", not "the file directive") and all three share one grammar:
//!
//! ```text
//! % badness-format <verb>              layout only
//! % badness-lint   <verb> [<rule>]     linting only, optionally one rule
//! % badness        <verb>              both at once
//! ```
//!
//! with `<verb>` one of:
//!
//! ```text
//! skip        the next construct
//! off … on    everything between the two
//! skip-file   the whole file, wherever the directive sits
//! ```
//!
//! Only the lint axis takes a `<rule>`, because only the linter has anything to
//! select; omitting it means every rule. The `: <reason>` tail is optional
//! everywhere and is never interpreted.
//!
//! ## The retired `% badness-ignore` family
//!
//! ```text
//! % badness-ignore <rule>: <reason>        → % badness-lint skip <rule>: <reason>
//! % badness-ignore-file <rule>: <reason>   → % badness-lint skip-file <rule>: <reason>
//! % badness-ignore-file: <reason>          → % badness-lint skip-file: <reason>
//! ```
//!
//! Still recognized, and resolved through exactly the same path as their
//! replacements — the deprecation is in the documentation, never in the
//! behavior. A directive spelling is user-facing API; breaking one silently
//! would be worse than carrying it. [`Directive::deprecated`] marks them, so a
//! lint rule reporting the retired spelling can reuse the parsed fact.
//!
//! ## Why this lives in the parser crate
//!
//! Both consumers need it and neither can reach the other: the formatter is
//! wasm-clean (and is what the dprint plugin embeds), the linter lives in the
//! root crate. Resolving a directive is a pure function of the tree, so it sits
//! below both.
//!
//! Active directives are recognized in [`SyntaxKind::COMMENT`] tokens. A `.dtx`
//! documentation line starts with `DOC_MARGIN`, not a comment; directive-shaped
//! prose there is retained as [`DirectiveOutcome::Unsupported`] so the linter can
//! explain why it is inert. Inside a `macrocode` chunk, `%` comments are ordinary
//! and directives work as everywhere else.

use std::collections::BTreeMap;

use rowan::{NodeOrToken, TextRange, TextSize};

use crate::syntax::{SyntaxKind, SyntaxNode, SyntaxToken};

/// Which subsystem a directive turns off.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Axis {
    /// `% badness-format …` — layout only. Lint findings are still reported.
    Format,
    /// `% badness-lint …` — linting only, for one rule or all of them.
    Lint,
    /// `% badness …` — layout *and* every lint rule.
    Both,
}

impl Axis {
    /// Whether a directive on this axis turns off layout.
    pub fn covers_format(self) -> bool {
        matches!(self, Axis::Format | Axis::Both)
    }

    /// Whether a directive on this axis turns off linting.
    pub fn covers_lint(self) -> bool {
        matches!(self, Axis::Lint | Axis::Both)
    }
}

/// The scope a directive applies to. The verb *is* the scope.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Verb {
    /// `skip` — the next meaningful sibling. When the directive comment binds
    /// forward into a `DOC_COMMENT` (parser trivia rule), the target is the
    /// whole construct that owns it, which is the shape an author writing a
    /// directive above `\begin{tikzpicture}` means.
    Skip,
    /// `off` — from the next meaningful thing (as [`Verb::Skip`] resolves it) to
    /// the matching `on`, or to end of file.
    Off,
    /// `on` — closes an open `off` with the same axis and rule. Inert without one.
    On,
    /// `skip-file` — the whole file, wherever in it the directive sits.
    SkipFile,
}

/// One directive, as written. Resolution against the tree happens in
/// [`Suppressions::build`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Directive {
    pub axis: Axis,
    pub verb: Verb,
    /// The rule the directive selects; `None` means every rule. Only ever `Some`
    /// on [`Axis::Lint`] — the other two axes have nothing to select.
    pub rule: Option<String>,
    /// Written in the retired `% badness-ignore` spelling. Behaves identically —
    /// this exists so a lint rule can report the retired spelling and offer the
    /// rewrite, without having to re-parse the comment.
    pub deprecated: bool,
}

/// What a recognized directive accomplished after placement and region matching.
///
/// The linter consumes this retained resolver fact for meta diagnostics; it must
/// not repeat the CST attachment walk or try to infer region state from the
/// merged suppression ranges.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum DirectiveOutcome {
    /// The directive targets a construct or file, opens a region that is later
    /// closed, or closes such a region.
    Honored,
    /// A `skip` has no following meaningful construct.
    DanglingSkip,
    /// An `on` has no matching open region with the same axis and rule.
    UnmatchedOn,
    /// An `off` has no matching `on`; its range still extends to EOF.
    UnclosedOff,
    /// The carrier or axis is recognized but unsupported by the consumer.
    Unsupported,
}

/// A parsed directive together with the exact carrier and family-name ranges,
/// plus its placement outcome. Consumers retain these facts so diagnostics never
/// need to parse comment text or repeat the attachment walk.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct LocatedDirective {
    pub directive: Directive,
    pub range: TextRange,
    pub family_range: TextRange,
    pub outcome: DirectiveOutcome,
}

/// Read a directive out of a comment token's text. Returns `None` for an
/// ordinary comment and for an unrecognized verb.
///
/// Leading `%`s are all stripped, so `%%% badness-format off` works; the verb
/// must be the first word after the family name, separated by whitespace.
pub fn parse_directive(comment: &str) -> Option<Directive> {
    let body = comment.trim_start_matches('%').trim_start();
    // Longest family name first, or a shorter one swallows a longer one's prefix
    // and the word-boundary check below rejects it for the wrong reason.
    if let Some(rest) = body.strip_prefix("badness-ignore-file") {
        // `…-file:` or a bare `…-file` is every rule; `…-file <rule>` is one.
        return Some(Directive {
            axis: Axis::Lint,
            verb: Verb::SkipFile,
            rule: parse_rule(rest),
            deprecated: true,
        });
    }
    if let Some(rest) = body.strip_prefix("badness-ignore") {
        // The retired node form always required a rule; a bare `% badness-ignore`
        // was inert and stays inert, rather than silently widening to every rule
        // on the way through the new grammar.
        return Some(Directive {
            axis: Axis::Lint,
            verb: Verb::Skip,
            rule: Some(parse_rule(rest)?),
            deprecated: true,
        });
    }
    let (axis, rest) = if let Some(rest) = body.strip_prefix("badness-format") {
        (Axis::Format, rest)
    } else if let Some(rest) = body.strip_prefix("badness-lint") {
        (Axis::Lint, rest)
    } else {
        (Axis::Both, body.strip_prefix("badness")?)
    };
    // The family name must end at a word boundary, so `% badness-formatting off`
    // and `% badnesslint skip` are ordinary comments.
    if !rest.starts_with([' ', '\t']) {
        return None;
    }
    let rest = rest.trim_start();
    let end = word_end(rest);
    let verb = match &rest[..end] {
        "skip" => Verb::Skip,
        "off" => Verb::Off,
        "on" => Verb::On,
        "skip-file" => Verb::SkipFile,
        _ => return None,
    };
    // Only the lint axis takes a selector. A word after the verb on another axis
    // is prose in the reason position, not a rule we should quietly honor.
    let rule = if axis == Axis::Lint {
        parse_rule(&rest[end..])
    } else {
        None
    };
    Some(Directive {
        axis,
        verb,
        rule,
        deprecated: false,
    })
}

/// The leading `<rule>` word of a `<rule>: <reason>` tail, or `None` when the
/// tail opens with `:` (a reason and no rule) or is empty.
fn parse_rule(tail: &str) -> Option<String> {
    let trimmed = tail.trim_start();
    let end = word_end(trimmed);
    if end == 0 {
        return None;
    }
    Some(trimmed[..end].to_string())
}

/// The end of the first word of `s`, delimited by `:` or whitespace.
fn word_end(s: &str) -> usize {
    s.find(|c: char| c == ':' || c.is_whitespace())
        .unwrap_or(s.len())
}

/// The byte ranges a file's directives suppress, resolved per axis.
///
/// Ranges are sorted and non-overlapping (touching ones are merged), so a
/// consumer can test containment with a plain scan and never has to reason
/// about nesting.
#[derive(Debug, Clone, Default)]
pub struct Suppressions {
    format: Vec<TextRange>,
    lint_all: Vec<TextRange>,
    lint_rules: BTreeMap<String, Vec<TextRange>>,
    directives: Vec<LocatedDirective>,
}

/// A region opened by an `off` and waiting for its `on`.
struct OpenRegion {
    axis: Axis,
    rule: Option<String>,
    start: TextSize,
    directive_index: usize,
}

impl Suppressions {
    /// Scan `root` for directives and resolve them into ranges.
    ///
    /// A `skip-file` becomes a range covering the whole document rather than a
    /// flag, so every consumer keeps one code path: whole-file suppression is
    /// just the widest region. (The document-level trailing-edge normalization
    /// and the `line_ending` post-pass still run over the result — the same
    /// carve-out protected regions already live under.)
    ///
    /// An `off` with no matching `on` runs to end of file, as it does in every
    /// other formatter that has the directive.
    pub fn build(root: &SyntaxNode) -> Self {
        let mut format = Vec::new();
        let mut lint_all = Vec::new();
        let mut lint_rules: BTreeMap<String, Vec<TextRange>> = BTreeMap::new();
        let mut directives = Vec::new();
        // Regions are keyed by axis *and* rule: a `% badness-lint off` covering
        // every rule is not closed by a `% badness-lint on some-rule`, which
        // speaks for a strictly narrower thing.
        let mut open: Vec<OpenRegion> = Vec::new();
        // End of the most recent directive comment. A region anchor may never
        // reach back past it — see the `Verb::Off` arm.
        let mut prev_directive_end = TextSize::new(0);

        for element in root.descendants_with_tokens() {
            let NodeOrToken::Token(token) = element else {
                continue;
            };
            let Some((carrier, range, supported)) = directive_carrier(&token) else {
                continue;
            };
            let Some(directive) = parse_directive(&carrier) else {
                continue;
            };
            let family = directive_family(&directive);
            let family_start = carrier
                .find(family)
                .expect("parsed directive contains its family name");
            let token_start = usize::from(range.start());
            let directive_index = directives.len();
            directives.push(LocatedDirective {
                directive: directive.clone(),
                range,
                family_range: TextRange::new(
                    TextSize::from((token_start + family_start) as u32),
                    TextSize::from((token_start + family_start + family.len()) as u32),
                ),
                outcome: if supported {
                    DirectiveOutcome::Honored
                } else {
                    DirectiveOutcome::Unsupported
                },
            });
            if !supported {
                continue;
            }
            let mut record = |range: TextRange, rule: &Option<String>| {
                if directive.axis.covers_format() {
                    format.push(range);
                }
                if directive.axis.covers_lint() {
                    match rule {
                        Some(rule) => lint_rules.entry(rule.clone()).or_default().push(range),
                        None => lint_all.push(range),
                    }
                }
            };
            match directive.verb {
                Verb::SkipFile => record(root.text_range(), &directive.rule),
                Verb::Skip => {
                    if let Some(range) = skip_target(&token) {
                        record(range, &directive.rule);
                    } else {
                        directives[directive_index].outcome = DirectiveOutcome::DanglingSkip;
                    }
                }
                // A region opens at the same place a `skip` would target: the
                // next meaningful thing. Anchoring to the raw byte after the
                // comment instead looks simpler and is wrong — an own-line `%`
                // binds *forward* into the following construct's `DOC_COMMENT`
                // (parser decision #9), so that construct begins at the comment,
                // ahead of the region, and a consumer testing containment would
                // find the very block the author meant to cover sticking out of
                // it. Resolving through the tree also picks up a preceding
                // comment run bound into the same `DOC_COMMENT`, which a byte
                // offset cannot see at all. Falls back to the byte after the
                // comment when nothing meaningful follows (a directive at EOF).
                //
                // Clamped so the anchor never reaches back past the previous
                // directive: consecutive own-line comments bind into *one*
                // `DOC_COMMENT`, so in `on` / `off` / `\b` the reopening `off`
                // resolves to a construct starting at the `on` — and the region
                // it opens would then swallow the very directive that closed the
                // one before it, fusing two deliberately separate regions into
                // one. The clamp is against directives only, so an ordinary
                // comment run above the directive is still covered.
                Verb::Off => {
                    let start = skip_target(&token)
                        .map(|r| r.start())
                        .unwrap_or_else(|| token.text_range().end())
                        .max(prev_directive_end);
                    if !open
                        .iter()
                        .any(|o| o.axis == directive.axis && o.rule == directive.rule)
                    {
                        directives[directive_index].outcome = DirectiveOutcome::UnclosedOff;
                        open.push(OpenRegion {
                            axis: directive.axis,
                            rule: directive.rule.clone(),
                            start,
                            directive_index,
                        });
                    }
                }
                Verb::On => {
                    if let Some(i) = open
                        .iter()
                        .position(|o| o.axis == directive.axis && o.rule == directive.rule)
                    {
                        let region = open.remove(i);
                        directives[region.directive_index].outcome = DirectiveOutcome::Honored;
                        record(
                            TextRange::new(region.start, token.text_range().start()),
                            &region.rule,
                        );
                    } else {
                        directives[directive_index].outcome = DirectiveOutcome::UnmatchedOn;
                    }
                }
            }
            prev_directive_end = token.text_range().end();
        }

        // Unclosed regions run to end of file.
        let eof = root.text_range().end();
        for region in open {
            let range = TextRange::new(region.start, eof);
            if region.axis.covers_format() {
                format.push(range);
            }
            if region.axis.covers_lint() {
                match &region.rule {
                    Some(rule) => lint_rules.entry(rule.clone()).or_default().push(range),
                    None => lint_all.push(range),
                }
            }
        }

        Self {
            format: merge(format),
            lint_all: merge(lint_all),
            lint_rules: lint_rules
                .into_iter()
                .map(|(rule, ranges)| (rule, merge(ranges)))
                .collect(),
            directives,
        }
    }

    /// Whether the document carries no effective suppression range — the fast
    /// path for the overwhelming majority of files, so a consumer can skip its
    /// per-node test.
    pub fn is_empty(&self) -> bool {
        self.format.is_empty() && self.lint_all.is_empty() && self.lint_rules.is_empty()
    }

    /// Ranges the formatter must reproduce byte-for-byte.
    pub fn format_ranges(&self) -> &[TextRange] {
        &self.format
    }

    /// Ranges in which *every* lint rule is suppressed.
    pub fn lint_all_ranges(&self) -> &[TextRange] {
        &self.lint_all
    }

    /// Ranges in which one named rule is suppressed.
    pub fn lint_rule_ranges(&self) -> &BTreeMap<String, Vec<TextRange>> {
        &self.lint_rules
    }

    /// Parsed directives in source order, including directives that resolve to
    /// no range (such as an unmatched `on`).
    pub fn directives(&self) -> &[LocatedDirective] {
        &self.directives
    }
}

/// A directive-bearing token's text, full carrier range, and whether that
/// carrier can take effect. Ordinary comments are active. A `.dtx` documentation
/// margin is retained for diagnostics, but its line is typeset source rather than
/// a comment, so it never contributes a suppression range.
fn directive_carrier(token: &SyntaxToken) -> Option<(String, TextRange, bool)> {
    match token.kind() {
        SyntaxKind::COMMENT => Some((token.text().to_owned(), token.text_range(), true)),
        SyntaxKind::DOC_MARGIN => {
            let start = token.text_range().start();
            let mut end = start;
            let mut text = String::new();
            let mut current = Some(token.clone());
            while let Some(part) = current {
                if part.kind() == SyntaxKind::NEWLINE {
                    break;
                }
                let part_text = part.text();
                if let Some(line_end) = part_text.find(['\r', '\n']) {
                    text.push_str(&part_text[..line_end]);
                    end = part.text_range().start() + TextSize::from(line_end as u32);
                    break;
                }
                text.push_str(part_text);
                end = part.text_range().end();
                current = part.next_token();
            }
            Some((text, TextRange::new(start, end), false))
        }
        _ => None,
    }
}

fn directive_family(directive: &Directive) -> &'static str {
    if directive.deprecated {
        return match directive.verb {
            Verb::SkipFile => "badness-ignore-file",
            Verb::Skip => "badness-ignore",
            Verb::Off | Verb::On => unreachable!("retired directives have no region verbs"),
        };
    }
    match directive.axis {
        Axis::Format => "badness-format",
        Axis::Lint => "badness-lint",
        Axis::Both => "badness",
    }
}

/// Sort and coalesce, merging ranges that overlap *or touch*. Touching ranges
/// merge because two adjacent `off`/`on` regions describe one continuous span of
/// suppressed text, and leaving them split would let a consumer that tests
/// containment miss an element straddling the seam.
fn merge(mut ranges: Vec<TextRange>) -> Vec<TextRange> {
    ranges.sort_by_key(|r| (r.start(), r.end()));
    let mut out: Vec<TextRange> = Vec::with_capacity(ranges.len());
    for range in ranges {
        match out.last_mut() {
            Some(last) if range.start() <= last.end() => {
                *last = TextRange::new(last.start(), last.end().max(range.end()));
            }
            _ => out.push(range),
        }
    }
    out
}

/// The range a node-scoped directive covers: the next non-trivia, non-comment
/// element after `token`, bubbling up through parents whose remaining siblings
/// are all trivia. A comment bound into a `DOC_COMMENT` targets the whole
/// construct that owns it, not a sibling — walking forward from such a comment
/// only ever finds pieces *inside* that construct (its control word, missing its
/// arguments), never the construct as a whole.
fn skip_target(token: &SyntaxToken) -> Option<TextRange> {
    if let Some(parent) = token.parent()
        && parent.kind() == SyntaxKind::DOC_COMMENT
    {
        return Some(parent.parent()?.text_range());
    }
    let mut current = token.clone();
    loop {
        let parent = current.parent()?;
        if let Some(range) = first_meaningful_after(&parent, &NodeOrToken::Token(current.clone())) {
            return Some(range);
        }
        let grand = parent.parent()?;
        if let Some(range) = first_meaningful_after(&grand, &NodeOrToken::Node(parent.clone())) {
            return Some(range);
        }
        // Guard against a non-progressing climb (a single-child spine).
        if grand == parent {
            return None;
        }
        current = grand.first_token()?;
    }
}

/// The range of the first non-trivia element of `parent` strictly after `after`.
fn first_meaningful_after(
    parent: &SyntaxNode,
    after: &NodeOrToken<SyntaxNode, SyntaxToken>,
) -> Option<TextRange> {
    let mut past = false;
    for element in parent.children_with_tokens() {
        if !past {
            past = &element == after;
            continue;
        }
        match &element {
            NodeOrToken::Token(t)
                if matches!(
                    t.kind(),
                    SyntaxKind::WHITESPACE | SyntaxKind::NEWLINE | SyntaxKind::COMMENT
                ) => {}
            _ => return Some(element.text_range()),
        }
    }
    None
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::parser::{LatexFlavor, LexConfig, parse, parse_with_flavor};

    fn suppressions_of(src: &str) -> Suppressions {
        Suppressions::build(&SyntaxNode::new_root(parse(src).green))
    }

    fn dtx_suppressions_of(src: &str) -> Suppressions {
        let parsed = parse_with_flavor(
            src,
            LexConfig {
                flavor: LatexFlavor::Document,
                dtx: true,
            },
        );
        assert_eq!(parsed.syntax().to_string(), src);
        Suppressions::build(&parsed.syntax())
    }

    #[test]
    fn classifies_inert_and_incomplete_directives() {
        for (src, expected) in [
            (
                "% badness-lint skip deprecated-command\n",
                DirectiveOutcome::DanglingSkip,
            ),
            (
                "% badness-lint on deprecated-command\n",
                DirectiveOutcome::UnmatchedOn,
            ),
            (
                "% badness-lint off deprecated-command\n\\bf\n",
                DirectiveOutcome::UnclosedOff,
            ),
        ] {
            let suppressions = suppressions_of(src);
            assert_eq!(suppressions.directives().len(), 1, "{src:?}");
            assert_eq!(suppressions.directives()[0].outcome, expected, "{src:?}");
        }
    }

    #[test]
    fn matched_and_targeted_directives_are_honored() {
        for src in [
            "% badness-lint skip deprecated-command\n\\bf\n",
            "% badness-lint off deprecated-command\n\\bf\n% badness-lint on deprecated-command\n",
            "% badness-lint skip-file deprecated-command\n",
        ] {
            let suppressions = suppressions_of(src);
            assert!(
                suppressions
                    .directives()
                    .iter()
                    .all(|located| located.outcome == DirectiveOutcome::Honored),
                "{src:?}: {:?}",
                suppressions.directives()
            );
        }
    }

    #[test]
    fn retains_dtx_doc_margin_directive_as_unsupported() {
        let src = "% badness-lint skip deprecated-command\nDocumentation.\n";
        let suppressions = dtx_suppressions_of(src);
        let [located] = suppressions.directives() else {
            panic!(
                "expected one retained directive: {:?}",
                suppressions.directives()
            );
        };
        assert_eq!(located.outcome, DirectiveOutcome::Unsupported);
        assert_eq!(
            &src[usize::from(located.range.start())..usize::from(located.range.end())],
            "% badness-lint skip deprecated-command"
        );
        assert!(suppressions.format_ranges().is_empty());
        assert!(suppressions.lint_all_ranges().is_empty());
        assert!(suppressions.lint_rule_ranges().is_empty());
    }

    #[test]
    fn retains_directives_with_their_carrier_ranges() {
        let src = "% a note\n% badness-ignore deprecated-command: legacy\n\\bf\n";
        let suppressions = suppressions_of(src);
        let retained = suppressions.directives();

        assert_eq!(retained.len(), 1);
        assert!(retained[0].directive.deprecated);
        assert_eq!(
            &src[usize::from(retained[0].range.start())..usize::from(retained[0].range.end())],
            "% badness-ignore deprecated-command: legacy"
        );
    }

    fn slices<'a>(src: &'a str, ranges: &[TextRange]) -> Vec<&'a str> {
        ranges
            .iter()
            .map(|r| &src[usize::from(r.start())..usize::from(r.end())])
            .collect()
    }

    fn directive(axis: Axis, verb: Verb) -> Directive {
        Directive {
            axis,
            verb,
            rule: None,
            deprecated: false,
        }
    }

    #[test]
    fn parses_every_form_on_every_axis() {
        for (family, axis) in [
            ("badness-format", Axis::Format),
            ("badness-lint", Axis::Lint),
            ("badness", Axis::Both),
        ] {
            for (word, verb) in [
                ("skip", Verb::Skip),
                ("off", Verb::Off),
                ("on", Verb::On),
                ("skip-file", Verb::SkipFile),
            ] {
                let text = format!("% {family} {word}");
                assert_eq!(
                    parse_directive(&text),
                    Some(directive(axis, verb)),
                    "parsing {text:?}"
                );
            }
        }
    }

    #[test]
    fn only_the_lint_axis_takes_a_rule() {
        assert_eq!(
            parse_directive("% badness-lint skip deprecated-command: legacy"),
            Some(Directive {
                axis: Axis::Lint,
                verb: Verb::Skip,
                rule: Some("deprecated-command".into()),
                deprecated: false,
            })
        );
        assert_eq!(
            parse_directive("% badness-format skip deprecated-command"),
            Some(directive(Axis::Format, Verb::Skip))
        );
        assert_eq!(
            parse_directive("% badness skip deprecated-command"),
            Some(directive(Axis::Both, Verb::Skip))
        );
    }

    #[test]
    fn lint_rule_is_optional_and_means_every_rule() {
        assert_eq!(
            parse_directive("% badness-lint skip-file: generated"),
            Some(directive(Axis::Lint, Verb::SkipFile))
        );
    }

    #[test]
    fn reason_is_optional_and_ignored() {
        assert_eq!(
            parse_directive("% badness-format skip: hand-aligned by eye"),
            Some(directive(Axis::Format, Verb::Skip))
        );
        assert_eq!(
            parse_directive("%badness skip-file:generated"),
            Some(directive(Axis::Both, Verb::SkipFile))
        );
    }

    #[test]
    fn repeated_percent_is_allowed() {
        assert_eq!(
            parse_directive("%%% badness-format off"),
            Some(directive(Axis::Format, Verb::Off))
        );
    }

    #[test]
    fn retired_ignore_family_still_parses() {
        assert_eq!(
            parse_directive("% badness-ignore deprecated-command: legacy"),
            Some(Directive {
                axis: Axis::Lint,
                verb: Verb::Skip,
                rule: Some("deprecated-command".into()),
                deprecated: true,
            })
        );
        assert_eq!(
            parse_directive("% badness-ignore-file deprecated-command: legacy"),
            Some(Directive {
                axis: Axis::Lint,
                verb: Verb::SkipFile,
                rule: Some("deprecated-command".into()),
                deprecated: true,
            })
        );
        assert_eq!(
            parse_directive("% badness-ignore-file: noisy"),
            Some(Directive {
                axis: Axis::Lint,
                verb: Verb::SkipFile,
                rule: None,
                deprecated: true,
            })
        );
    }

    #[test]
    fn bare_retired_node_directive_stays_inert() {
        assert_eq!(parse_directive("% badness-ignore"), None);
        assert_eq!(parse_directive("% badness-ignore: no rule named"), None);
    }

    #[test]
    fn non_directives_are_inert() {
        for text in [
            "% just a note",
            "% badness",                 // no verb
            "% badness-lint",            // no verb
            "% badness-format nonsense", // unknown verb
            "% badnessformat off",       // no word boundary
            "% badness-formatting off",  // no word boundary
            "% badnesslint skip",        // no word boundary
            "% the badness-format off",  // not at the start
        ] {
            assert_eq!(parse_directive(text), None, "expected {text:?} to be inert");
        }
    }

    #[test]
    fn skip_targets_the_documented_construct() {
        let src = "% badness-format skip: hand-aligned\n\\begin{tikzpicture}\n\\draw (0,0);\n\\end{tikzpicture}\n";
        let s = suppressions_of(src);
        assert_eq!(slices(src, s.format_ranges()), vec![src.trim_end()]);
        assert!(s.lint_all_ranges().is_empty(), "format axis must not lint");
    }

    #[test]
    fn region_spans_from_off_to_on() {
        let src = "\\alpha\n% badness-format off\n\\beta\n% badness-format on\n\\gamma\n";
        let s = suppressions_of(src);
        assert_eq!(
            slices(src, s.format_ranges()),
            vec!["% badness-format off\n\\beta\n"]
        );
    }

    #[test]
    fn region_covers_a_leading_comment_run() {
        let src = "\\alpha\n% a note\n% badness-format off\n\\beta\n% badness-format on\n";
        let s = suppressions_of(src);
        assert_eq!(
            slices(src, s.format_ranges()),
            vec!["% a note\n% badness-format off\n\\beta\n"]
        );
    }

    #[test]
    fn unclosed_region_runs_to_end_of_file() {
        let src = "\\alpha\n% badness-format off\n\\beta\n\\gamma\n";
        let s = suppressions_of(src);
        assert_eq!(
            slices(src, s.format_ranges()),
            vec!["% badness-format off\n\\beta\n\\gamma\n"]
        );
    }

    #[test]
    fn both_family_suppresses_both_axes() {
        let src = "% badness off\n\\beta\n% badness on\n";
        let s = suppressions_of(src);
        assert_eq!(s.format_ranges(), s.lint_all_ranges());
        assert_eq!(
            slices(src, s.lint_all_ranges()),
            vec!["% badness off\n\\beta\n"]
        );
    }

    #[test]
    fn format_on_does_not_close_a_both_region() {
        let src = "% badness off\n\\beta\n% badness-format on\n\\gamma\n";
        let s = suppressions_of(src);
        assert_eq!(
            slices(src, s.lint_all_ranges()),
            vec!["% badness off\n\\beta\n% badness-format on\n\\gamma\n"]
        );
    }

    #[test]
    fn rule_selective_on_does_not_close_an_every_rule_region() {
        let src = "% badness-lint off\n\\beta\n% badness-lint on deprecated-command\n\\gamma\n";
        let s = suppressions_of(src);
        assert_eq!(s.lint_all_ranges().len(), 1);
        assert!(
            slices(src, s.lint_all_ranges())[0].ends_with("\\gamma\n"),
            "the every-rule region stays open to EOF"
        );
    }

    #[test]
    fn lint_region_is_rule_selective() {
        let src =
            "% badness-lint off deprecated-command\n\\beta\n% badness-lint on deprecated-command\n";
        let s = suppressions_of(src);
        assert!(s.lint_all_ranges().is_empty(), "one rule, not all of them");
        assert!(s.format_ranges().is_empty(), "lint axis must not format");
        let ranges = s
            .lint_rule_ranges()
            .get("deprecated-command")
            .expect("rule recorded");
        assert_eq!(
            slices(src, ranges),
            vec!["% badness-lint off deprecated-command\n\\beta\n"]
        );
    }

    #[test]
    fn skip_file_covers_the_document_on_its_axis() {
        let src = "\\alpha\n% badness-format skip-file: generated\n\\beta\n";
        let s = suppressions_of(src);
        assert_eq!(slices(src, s.format_ranges()), vec![src]);
        assert!(s.lint_all_ranges().is_empty());
    }

    #[test]
    fn stray_on_is_inert() {
        let src = "\\alpha\n% badness-format on\n\\beta\n";
        assert!(suppressions_of(src).is_empty());
    }

    #[test]
    fn overlapping_ranges_merge() {
        let src = "% badness-format skip-file: generated\n% badness-format off\n\\b\n";
        let s = suppressions_of(src);
        assert_eq!(slices(src, s.format_ranges()), vec![src]);
    }

    #[test]
    fn reopened_region_does_not_swallow_its_own_closer() {
        let src = "% badness-format off\n\\a\n% badness-format on\n% badness-format off\n\\b\n% badness-format on\n";
        let s = suppressions_of(src);
        assert_eq!(
            slices(src, s.format_ranges()),
            vec![
                "% badness-format off\n\\a\n",
                "\n% badness-format off\n\\b\n"
            ]
        );
    }

    #[test]
    fn retired_and_current_spellings_resolve_identically() {
        fn covers_target(src: &str, ranges: &[TextRange]) -> bool {
            let at = TextSize::new(src.find("\\bf").expect("has a target") as u32);
            ranges.iter().any(|r| r.contains(at))
        }
        for (old, new) in [
            (
                "% badness-ignore deprecated-command: legacy\n\\bf x\n",
                "% badness-lint skip deprecated-command: legacy\n\\bf x\n",
            ),
            (
                "% badness-ignore-file deprecated-command: legacy\n\\bf x\n",
                "% badness-lint skip-file deprecated-command: legacy\n\\bf x\n",
            ),
        ] {
            for (src, label) in [(old, "retired"), (new, "current")] {
                let s = suppressions_of(src);
                let ranges = s
                    .lint_rule_ranges()
                    .get("deprecated-command")
                    .unwrap_or_else(|| panic!("{label} spelling records the rule: {src:?}"));
                assert!(
                    covers_target(src, ranges),
                    "{label} spelling must cover its target: {src:?}"
                );
                assert!(
                    s.lint_all_ranges().is_empty() && s.format_ranges().is_empty(),
                    "{label} spelling is lint-only and rule-selective: {src:?}"
                );
            }
        }
        let old = suppressions_of("% badness-ignore-file: noisy\n\\bf x\n");
        let new = suppressions_of("% badness-lint skip-file: noisy\n\\bf x\n");
        assert_eq!(old.lint_all_ranges().len(), 1);
        assert_eq!(new.lint_all_ranges().len(), 1);
        assert!(old.lint_rule_ranges().is_empty() && new.lint_rule_ranges().is_empty());
    }

    #[test]
    fn clean_document_has_no_suppressions() {
        assert!(suppressions_of("\\alpha\n% an ordinary comment\n\\beta\n").is_empty());
    }
}