Skip to main content

rustango_cms/
metrics.rs

1//! Content metrics — word count, estimated reading time, and a
2//! readability score.
3//!
4//! Computed server-side at editor-open from the **content-bearing
5//! extension widget values** (the markdown / text fields the author is
6//! editing), so the editor shows metrics without opening the preview
7//! Pure functions — [`analyze`] takes a string and
8//! [`collect_widget_text`] gathers the text to feed it.
9
10use crate::widget::{Widget, WidgetKind};
11
12/// Average adult reading speed (words per minute) for the reading-time
13/// estimate. Common estimates use ~200–265; 200 is the conservative
14/// end so the estimate doesn't undersell length.
15const WORDS_PER_MINUTE: usize = 200;
16
17/// Word count + reading time + readability for a chunk of content.
18#[derive(Debug, Clone, PartialEq, serde::Serialize)]
19pub struct ContentMetrics {
20    pub words: usize,
21    /// Minutes, `ceil(words / 200)`. Zero when there are no words.
22    pub reading_time_min: usize,
23    /// Flesch Reading Ease (higher = easier; ~0–100 typical). Zero when
24    /// empty.
25    pub flesch_reading_ease: f64,
26    /// Coarse band for the score: `Easy` / `Standard` / `Difficult`,
27    /// or `—` when empty.
28    pub reading_ease_label: String,
29}
30
31/// Concatenate the text of content-bearing widgets — `Text`,
32/// `Textarea`, `Markdown`, `RichText` — skipping choosers, numbers,
33/// booleans, and the like. The result feeds [`analyze`].
34#[must_use]
35pub fn collect_widget_text(widgets: &[Widget]) -> String {
36    widgets
37        .iter()
38        .filter(|w| {
39            matches!(
40                w.kind,
41                WidgetKind::Text
42                    | WidgetKind::Textarea
43                    | WidgetKind::Markdown
44                    | WidgetKind::RichText
45            )
46        })
47        .map(|w| w.value.as_str())
48        .collect::<Vec<_>>()
49        .join("\n")
50}
51
52/// Word count + reading time + Flesch reading ease for `text`. HTML
53/// tags and light markdown punctuation are stripped first, so the same
54/// function works on markdown source, rendered HTML, or plain text.
55#[must_use]
56pub fn analyze(text: &str) -> ContentMetrics {
57    let plain = strip_markup(text);
58    let words: Vec<&str> = plain
59        .split_whitespace()
60        .filter(|w| w.chars().any(char::is_alphanumeric))
61        .collect();
62    let word_count = words.len();
63    if word_count == 0 {
64        return ContentMetrics {
65            words: 0,
66            reading_time_min: 0,
67            flesch_reading_ease: 0.0,
68            reading_ease_label: "—".to_owned(),
69        };
70    }
71    let reading_time_min = word_count.div_ceil(WORDS_PER_MINUTE);
72    // Sentence terminators; at least one so the ratio is finite.
73    let sentences = plain
74        .chars()
75        .filter(|c| matches!(c, '.' | '!' | '?'))
76        .count()
77        .max(1);
78    let syllables: usize = words.iter().map(|w| syllables_in(w)).sum();
79
80    let wps = word_count as f64 / sentences as f64;
81    let spw = syllables as f64 / word_count as f64;
82    let flesch = 206.835 - 1.015 * wps - 84.6 * spw;
83    let flesch = (flesch * 10.0).round() / 10.0;
84
85    let label = if flesch >= 70.0 {
86        "Easy"
87    } else if flesch >= 50.0 {
88        "Standard"
89    } else {
90        "Difficult"
91    };
92    ContentMetrics {
93        words: word_count,
94        reading_time_min,
95        flesch_reading_ease: flesch,
96        reading_ease_label: label.to_owned(),
97    }
98}
99
100/// Strip HTML tags and replace common markdown punctuation with spaces
101/// so word splitting sees content, not syntax. Deliberately light — an
102/// exact parse isn't needed for a count/estimate.
103fn strip_markup(text: &str) -> String {
104    let mut no_tags = String::with_capacity(text.len());
105    let mut in_tag = false;
106    for c in text.chars() {
107        match c {
108            '<' => in_tag = true,
109            '>' => in_tag = false,
110            _ if !in_tag => no_tags.push(c),
111            _ => {}
112        }
113    }
114    no_tags
115        .chars()
116        .map(|c| match c {
117            '#' | '*' | '_' | '`' | '[' | ']' | '(' | ')' | '!' | '|' => ' ',
118            other => other,
119        })
120        .collect()
121}
122
123/// Rough English syllable count — number of vowel groups, with a silent
124/// trailing-`e` correction, floored at 1. Good enough for a readability
125/// estimate, not a dictionary.
126fn syllables_in(word: &str) -> usize {
127    let chars: Vec<char> = word
128        .chars()
129        .filter(char::is_ascii_alphabetic)
130        .map(|c| c.to_ascii_lowercase())
131        .collect();
132    if chars.is_empty() {
133        return 0;
134    }
135    let is_vowel = |c: char| matches!(c, 'a' | 'e' | 'i' | 'o' | 'u' | 'y');
136    let mut count = 0usize;
137    let mut prev_vowel = false;
138    for &c in &chars {
139        let v = is_vowel(c);
140        if v && !prev_vowel {
141            count += 1;
142        }
143        prev_vowel = v;
144    }
145    // Silent trailing 'e' (e.g. "make", "code") — drop one group.
146    if chars.len() > 2
147        && *chars.last().unwrap() == 'e'
148        && !is_vowel(chars[chars.len() - 2])
149        && count > 1
150    {
151        count -= 1;
152    }
153    count.max(1)
154}
155
156#[cfg(test)]
157mod tests {
158    use super::*;
159
160    #[test]
161    fn counts_words_and_reading_time() {
162        let m = analyze("Hello world. This is a short test.");
163        assert_eq!(m.words, 7);
164        assert_eq!(m.reading_time_min, 1); // <200 words → 1 min
165    }
166
167    #[test]
168    fn reading_time_rounds_up_per_200_words() {
169        let text = "word ".repeat(250);
170        assert_eq!(analyze(&text).reading_time_min, 2); // ceil(250/200)
171        let text2 = "word ".repeat(200);
172        assert_eq!(analyze(&text2).reading_time_min, 1);
173    }
174
175    #[test]
176    fn strips_html_and_markdown() {
177        let m = analyze("<p>Hello <strong>world</strong></p>");
178        assert_eq!(m.words, 2);
179        let md = analyze("# Heading\n\n**Bold** and `code` words here");
180        // "Heading Bold and code words here" → 6 words (syntax stripped).
181        assert_eq!(md.words, 6);
182    }
183
184    #[test]
185    fn empty_text_is_all_zero_with_dash_label() {
186        let m = analyze("   \n  ");
187        assert_eq!(m.words, 0);
188        assert_eq!(m.reading_time_min, 0);
189        assert_eq!(m.reading_ease_label, "—");
190    }
191
192    #[test]
193    fn readability_label_bands() {
194        // Simple short sentences read "Easy"; long Latinate ones harder.
195        let easy = analyze("The cat sat on the mat. The dog ran.");
196        assert_eq!(easy.reading_ease_label, "Easy", "{easy:?}");
197        let hard = analyze(
198            "Consequently, the aforementioned institutional methodologies \
199             necessitated comprehensive reconsideration.",
200        );
201        assert!(
202            hard.flesch_reading_ease < easy.flesch_reading_ease,
203            "dense prose should score lower: {hard:?} vs {easy:?}"
204        );
205    }
206
207    #[test]
208    fn collect_widget_text_only_content_kinds() {
209        let widgets = vec![
210            Widget::new(WidgetKind::Text, "title", "Title").with_value("Hello there"),
211            Widget::new(WidgetKind::Markdown, "body", "Body").with_value("more words"),
212            Widget::new(WidgetKind::Number, "rank", "Rank").with_value("5"),
213            Widget::new(WidgetKind::MediaPicker, "img", "Image").with_value("42"),
214        ];
215        let text = collect_widget_text(&widgets);
216        assert!(text.contains("Hello there"));
217        assert!(text.contains("more words"));
218        assert!(!text.contains('5'), "number widget excluded: {text}");
219        assert!(!text.contains("42"), "chooser widget excluded: {text}");
220        assert_eq!(analyze(&text).words, 4);
221    }
222}