redink 0.1.10

A spellchecker for prose — a TUI for humans, a JSON CLI for agents
//! In-file directives: HTML comments of the form `<!-- redink:... -->` that a
//! Markdown author uses to steer the checker. They vanish from any rendered
//! output (pandoc drops or hides comments), so they cost the manuscript
//! nothing.
//!
//! - `<!-- redink:off -->` … `<!-- redink:on -->` — skip everything between.
//!   Works between blocks or inside a sentence. Not nestable: a second `off`
//!   while already off is reported and ignored. Either marker may carry an
//!   optional reason after the command (`<!-- redink:off Kesh's dialect -->`),
//!   which is echoed back in any warning about that marker.
//! - `<!-- redink:allow Vorld =Kesh -->` — accept the listed words anywhere in
//!   this file. Bare words match any casing, `=Word` exact casing only, the
//!   same convention as `.redink.dic`; possessives are covered automatically.
//!
//! Mistakes are reported rather than guessed around, because the failure mode
//! of a skip marker is silence: an `off` that is never switched back on skips
//! to the end of the file *and* warns, so a forgotten `on` cannot quietly hide
//! half a chapter. Only comments the Markdown parser reports as HTML count, so
//! a directive quoted inside a code block is inert.

use std::ops::Range;

use hashbrown::HashSet;

use crate::dict::{canonical, strip_possessive};

const PREFIX: &str = "redink:";

/// What a [`Warning`] is about.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Kind {
    /// An `off` that is never switched back on, carrying its reason, if it
    /// gave one. Singled out because it silently swallows the rest of a file,
    /// so the TUI raises it where the author can't miss it.
    UnclosedOff { reason: Option<String> },
    /// Anything else: unknown, unbalanced, or empty directives. These are
    /// ignored, so they cost nothing but the author's intent.
    Malformed,
}

/// A problem with a directive, located by the byte offset of its comment.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct Warning {
    pub byte_offset: usize,
    pub kind: Kind,
    pub message: String,
}

/// Words a file accepts via `redink:allow`, file-wide.
#[derive(Debug, Default, Clone)]
pub struct Allow {
    /// Case-insensitive entries, stored lowercase.
    ci: HashSet<String>,
    /// Exact-case entries.
    cs: HashSet<String>,
}

impl Allow {
    fn insert(&mut self, entry: &str) {
        match entry.strip_prefix('=') {
            Some(exact) => {
                self.cs.insert(canonical(exact));
            }
            None => {
                self.ci.insert(canonical(entry).to_lowercase());
            }
        }
    }

    pub fn is_empty(&self) -> bool {
        self.ci.is_empty() && self.cs.is_empty()
    }

    /// True if `word` (or its possessive stem) was allowed in this file.
    pub fn contains(&self, word: &str) -> bool {
        if self.is_empty() {
            return false;
        }
        let has = |w: &str| {
            self.cs.contains(w) || (!self.ci.is_empty() && self.ci.contains(&w.to_lowercase()))
        };
        has(word) || strip_possessive(word).is_some_and(has)
    }
}

/// Everything the directives in one file amount to.
#[derive(Debug, Default)]
pub struct Directives {
    /// Spans switched off, each from the start of its `off` comment to the
    /// end of its `on` comment (or end of file).
    pub skips: Vec<Range<usize>>,
    pub allow: Allow,
    pub warnings: Vec<Warning>,
}

/// One HTML comment: its full span (`<!--` through `-->`) and its body.
struct Comment<'a> {
    span: Range<usize>,
    body: &'a str,
}

/// Every complete `<!-- ... -->` comment inside `src[range]`, in order.
/// `range` is a span the Markdown parser reported as HTML, so this never
/// looks inside code or prose.
fn comments_in(src: &str, range: Range<usize>) -> impl Iterator<Item = Comment<'_>> {
    let mut at = range.start;
    let end = range.end;
    std::iter::from_fn(move || {
        let open = at + src[at..end].find("<!--")?;
        let body_start = open + 4;
        let close = body_start + src[body_start..end].find("-->")?;
        at = close + 3;
        Some(Comment {
            span: open..at,
            body: &src[body_start..close],
        })
    })
}

/// Interpret the directives among the HTML spans of a file. `html` holds the
/// spans the Markdown parser reported as HTML, in source order.
pub fn collect(src: &str, html: &[Range<usize>]) -> Directives {
    let mut out = Directives::default();
    // Start offset and reason of the open `off`, if checking is currently
    // switched off.
    let mut off_since: Option<(usize, &str)> = None;

    for comment in html.iter().flat_map(|r| comments_in(src, r.clone())) {
        let body = comment.body.trim();
        let Some(rest) = strip_prefix_ignore_case(body, PREFIX) else {
            continue;
        };
        let at = comment.span.start;
        let mut words = rest.split_whitespace();
        let command = words.next().unwrap_or("");
        // `rest` starts with the command, so whatever follows it is the
        // (optional) free-text reason.
        let reason = rest[command.len()..].trim();
        let mut warn = |message: String| {
            out.warnings.push(Warning {
                byte_offset: at,
                kind: Kind::Malformed,
                message,
            })
        };
        match command {
            "off" => match off_since {
                Some(_) => warn(format!(
                    "redink:off{} while checking is already off; ignored",
                    describe(reason)
                )),
                None => off_since = Some((at, reason)),
            },
            "on" => match off_since.take() {
                Some((start, _)) => out.skips.push(start..comment.span.end),
                None => warn(format!(
                    "redink:on{} without a preceding redink:off; ignored",
                    describe(reason)
                )),
            },
            "allow" => {
                let mut any = false;
                for w in words.filter(|w| *w != "=") {
                    out.allow.insert(w);
                    any = true;
                }
                if !any {
                    warn("redink:allow lists no words".into());
                }
            }
            _ => warn(format!(
                "unknown directive `{body}` (expected redink:off, redink:on, or redink:allow)"
            )),
        }
    }

    if let Some((start, reason)) = off_since {
        out.skips.push(start..src.len());
        out.warnings.push(Warning {
            byte_offset: start,
            kind: Kind::UnclosedOff {
                reason: (!reason.is_empty()).then(|| reason.to_string()),
            },
            message: format!(
                "redink:off{} is never switched back on; the rest of the file is unchecked",
                describe(reason)
            ),
        });
    }
    out
}

/// A marker's reason for display in a warning (` ("Kesh's dialect")`), or
/// nothing when it gave none.
fn describe(reason: &str) -> String {
    if reason.is_empty() {
        String::new()
    } else {
        format!(" (\u{201c}{reason}\u{201d})")
    }
}

/// `s` without a leading `prefix`, compared ASCII-case-insensitively — so a
/// miscased `Redink:off` is caught as a malformed directive rather than
/// silently treated as an ordinary comment.
fn strip_prefix_ignore_case<'a>(s: &'a str, prefix: &str) -> Option<&'a str> {
    let head = s.get(..prefix.len())?;
    head.eq_ignore_ascii_case(prefix)
        .then(|| s[prefix.len()..].trim_start())
}

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

    /// Treat the whole source as one HTML span — enough to exercise the
    /// directive grammar without a Markdown parser.
    fn collect_all(src: &str) -> Directives {
        collect(src, std::slice::from_ref(&(0..src.len())))
    }

    #[test]
    fn off_on_pair_skips_between() {
        let src = "a <!-- redink:off --> b <!-- redink:on --> c";
        let d = collect_all(src);
        assert!(d.warnings.is_empty(), "{:?}", d.warnings);
        assert_eq!(d.skips, vec![2..src.find(" c").unwrap()]);
    }

    #[test]
    fn unclosed_off_skips_to_eof_and_warns() {
        let src = "a <!-- redink:off --> b c";
        let d = collect_all(src);
        assert_eq!(d.skips, vec![2..src.len()]);
        assert_eq!(d.warnings.len(), 1);
        assert_eq!(d.warnings[0].byte_offset, 2);
        assert_eq!(d.warnings[0].kind, Kind::UnclosedOff { reason: None });
        assert!(d.warnings[0].message.contains("never switched back on"));
    }

    #[test]
    fn reasons_are_accepted_and_echoed() {
        let src = "<!-- redink:off Kesh's dialect --> a <!-- redink:on end of dialect --> b";
        let d = collect_all(src);
        assert!(d.warnings.is_empty(), "{:?}", d.warnings);
        assert_eq!(d.skips.len(), 1);

        let d = collect_all("x <!-- redink:off  Kesh's  dialect --> y");
        assert_eq!(
            d.warnings[0].kind,
            Kind::UnclosedOff {
                reason: Some("Kesh's  dialect".into())
            }
        );
        assert!(
            d.warnings[0]
                .message
                .contains("\u{201c}Kesh's  dialect\u{201d}"),
            "{}",
            d.warnings[0].message
        );
    }

    #[test]
    fn stray_on_and_double_off_warn() {
        let src = "<!-- redink:on --> <!-- redink:off --> <!-- redink:off --> x <!-- redink:on -->";
        let d = collect_all(src);
        assert_eq!(d.warnings.len(), 2, "{:?}", d.warnings);
        assert!(d.warnings[0].message.contains("without a preceding"));
        assert!(d.warnings[1].message.contains("already off"));
        assert!(d.warnings.iter().all(|w| w.kind == Kind::Malformed));
        // The region runs from the *first* off.
        assert_eq!(
            d.skips,
            vec![src.find("<!-- redink:off").unwrap()..src.len()]
        );
    }

    #[test]
    fn malformed_directives_warn() {
        for bad in [
            "<!-- redink:of -->",
            "<!-- Redink:Off -->",
            "<!-- redink:off: dialect -->",
            "<!-- redink:allow -->",
            "<!-- redink: -->",
        ] {
            let d = collect_all(bad);
            assert_eq!(d.warnings.len(), 1, "{bad}: {:?}", d.warnings);
            assert!(d.skips.is_empty(), "{bad}");
        }
    }

    #[test]
    fn ordinary_comments_are_not_directives() {
        let d = collect_all("<!-- TODO: redink:off later --> <!-- just a note -->");
        assert!(d.warnings.is_empty());
        assert!(d.skips.is_empty());
    }

    #[test]
    fn allow_honours_case_and_possessives() {
        let d = collect_all("<!--\n  redink:allow vorld =Kesh\n  Zeb\n-->");
        assert!(d.warnings.is_empty(), "{:?}", d.warnings);
        let a = &d.allow;
        assert!(a.contains("vorld") && a.contains("Vorld") && a.contains("VORLD"));
        assert!(a.contains("Kesh") && a.contains("Kesh's"));
        assert!(!a.contains("kesh"), "exact-case entry matched other casing");
        assert!(a.contains("zeb"), "entries may span lines");
        assert!(!a.contains("world"));
    }

    #[test]
    fn allow_canonicalizes_possessive_entries() {
        let d = collect_all("<!-- redink:allow Atrax's -->");
        assert!(d.allow.contains("Atrax") && d.allow.contains("atrax's"));
    }
}