texplain 0.1.0

Strip LaTeX to plain text with 1:1 line mapping, so prose linters report the source line.
Documentation
//! Regex-based detection and removal of LaTeX remnant lines.
//!
//! After stripping LaTeX commands, some lines contain only debris: bare
//! dimension values, single package names, label keys, etc. These are not
//! useful prose and should be blanked so downstream linters ignore them.

use std::sync::LazyLock;

use regex::RegexSet;

/// Raw regex patterns that identify remnant (non-prose) lines.
///
/// Each pattern is tested as a full-match against the trimmed line.
static REMNANT_PATTERNS: &[&str] = &[
    r"^\s*$",
    r"(?i)^\d+(\.\d+)?(cm|pt|em|in|ex)?\s*$",
    r"^\s*(\[[^\]]*\]\s*)+\s*$",
    r"^\([^)]*\)\s*$",
    r"(?i)^(empty|white|centering|large|vfill|raggedright|sffamily|paperheight|paperwidth|title\.pdf)\s*$",
    r"^[a-zA-Z]*\d+[a-zA-Z]*\*?\s*$",
    // single word (possibly capitalised): "Author", "inputenc", "ngerman"
    r"^[a-zA-Z][a-zA-Z0-9-]*\s*$",
    r"^[a-zA-Z0-9_-]+:[a-zA-Z0-9_-]+\s*$",
    // tabular column-spec debris (contains @)
    r"^tabular.*$",
    // lines that are only punctuation and whitespace, with no letters or digits.
    // Dropping a command can leave its trailing punctuation alone on the line:
    // `\verb|\and|:` strips to a bare `:`.
    r"^[[:punct:]\s]+$",
    // key=value package/option debris: "maxbibnames=99," "style=alphabetic,"
    // The value may be empty: `country={}}` strips to a bare `country=`.
    r"^[\w.-]+=[\w./*-]*(,\s*)?$",
    // ]-prefixed leftovers from multi-line optional args: "]biblatex"
    r"^\].*$",
    // file paths / resource names: "refs.bib", "title.pdf", ".pdf"
    r"^\.?[\w./-]*\.\w+\s*$",
    // paths starting with ../ or ./ (e.g. from \graphicspath)
    r"^\.\./.*$",
    r"^\./.*$",
    // short fragment ending in comma/semicolon (title-page debris, list items)
    r"^(\S+\s+){0,5}\S+[,;]\s*$",
];

/// The remnant patterns as a single automaton, built once on first access.
///
/// A [`RegexSet`] matches every pattern in one pass over the line, rather than
/// running each of them in turn.  Nothing here reports *which* pattern matched,
/// so the set is exactly the right tool.
///
/// The patterns are compile-time constants and `patterns_are_valid_regex`
/// proves they compile, so construction cannot fail in practice.
static REMNANTS: LazyLock<RegexSet> = LazyLock::new(|| {
    RegexSet::new(REMNANT_PATTERNS)
        .unwrap_or_else(|e| unreachable!("remnant patterns must compile: {e}"))
});

/// Return `true` if the line is leftover LaTeX debris rather than prose.
///
/// Debris is what survives stripping a line that never held prose to begin
/// with: a bare dimension (`3cm`), a label key (`sec:intro`), a package name,
/// a file path.  The line is trimmed before testing.
///
/// The patterns are deliberately aggressive, and they judge a line in
/// isolation.  A short line of real prose can match: `is_remnant("visible")`
/// is `true`, because a lone word is far more often markup debris than a
/// sentence.  That trade is right for a whole document and wrong for a single
/// line typed by hand, which is why [`crate::strip_line`] does not apply it.
#[must_use]
pub fn is_remnant(line: &str) -> bool {
    REMNANTS.is_match(line.trim())
}

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

    #[test]
    fn blank_line_is_remnant() {
        assert!(is_remnant(""), "empty line is a remnant");
        assert!(is_remnant("   "), "whitespace-only line is a remnant");
    }

    #[test]
    fn dimension_is_remnant() {
        assert!(is_remnant("3cm"), "bare dimension is a remnant");
        assert!(is_remnant("1.5pt"), "decimal dimension is a remnant");
    }

    #[test]
    fn label_key_is_remnant() {
        assert!(is_remnant("sec:stress"), "label key is a remnant");
    }

    #[test]
    fn package_name_is_remnant() {
        assert!(is_remnant("inputenc"), "single package name is a remnant");
    }

    #[test]
    fn untrimmed_line_is_remnant() {
        assert!(is_remnant("  inputenc  "), "surrounding whitespace is ignored");
    }

    #[test]
    fn prose_is_not_remnant() {
        let prose = "Prose with nested commands bold and italic";
        assert!(!is_remnant(prose), "real prose must survive");
    }

    /// Guards the `unreachable!` in [`REMNANTS`]: if a pattern ever stops
    /// compiling, this fails here rather than panicking at first use.
    #[test]
    fn patterns_are_valid_regex() {
        for pat in REMNANT_PATTERNS {
            assert!(RegexSet::new([pat]).is_ok(), "invalid remnant regex `{pat}`");
        }
    }
}