fallow_extract/
sfc_css.rs

1//! Dead scoped-CSS class detection for Vue/Svelte single-file components.
2//!
3//! A class defined in a `<style scoped>` block applies only to its own
4//! component's markup (that is what `scoped` means), so a scoped class whose
5//! name appears nowhere else in the same SFC is a cleanup candidate. The
6//! "appears nowhere else" test is deliberately broad: any occurrence of the
7//! class name as a whole token anywhere outside the `<style>` blocks (a static
8//! `class="..."`, a dynamic `:class="{ name: x }"` key, a `class:name`
9//! directive, or even a string in `<script>`) counts as a use. That keeps the
10//! signal conservative (it errs toward "used"), so it is reported as a candidate
11//! rather than a hard dead-code finding.
12
13use std::sync::LazyLock;
14
15use rustc_hash::FxHashSet;
16
17use crate::ExportName;
18use crate::css::extract_css_module_exports;
19
20/// Matches `<style ...>BODY</style>` blocks, capturing the opening-tag
21/// attributes and the body. Mirrors the SFC style scanner: handles `>` inside
22/// quoted attribute values.
23static STYLE_BLOCK_RE: LazyLock<regex::Regex> = LazyLock::new(|| {
24    crate::static_regex(
25        r#"(?is)<style\b(?P<attrs>(?:[^>"']|"[^"]*"|'[^']*')*)>(?P<body>[\s\S]*?)</style>"#,
26    )
27});
28
29/// Returns `true` when an opening-`<style>` attribute string carries a bare
30/// `scoped` attribute.
31fn has_scoped_attr(attrs: &str) -> bool {
32    attrs
33        .split(|c: char| c.is_whitespace() || c == '=' || c == '"' || c == '\'')
34        .any(|token| token.eq_ignore_ascii_case("scoped"))
35}
36
37/// Returns `true` when the `<style>` block declares a non-CSS preprocessor
38/// language (`scss` / `sass` / `less` / `stylus` / `postcss`), which lightningcss
39/// does not parse, so we skip scoped-deadness analysis for it.
40fn has_non_css_lang(attrs: &str) -> bool {
41    let lower = attrs.to_ascii_lowercase();
42    has_preprocessor_lang_value(&lower)
43        || [
44            "lang=\"stylus\"",
45            "lang='stylus'",
46            "lang=\"postcss\"",
47            "lang='postcss'",
48        ]
49        .iter()
50        .any(|needle| lower.contains(needle))
51}
52
53fn has_preprocessor_lang(attrs: &str) -> bool {
54    has_preprocessor_lang_value(&attrs.to_ascii_lowercase())
55}
56
57fn has_preprocessor_lang_value(lower_attrs: &str) -> bool {
58    [
59        "lang=\"scss\"",
60        "lang='scss'",
61        "lang=\"sass\"",
62        "lang='sass'",
63        "lang=\"less\"",
64        "lang='less'",
65    ]
66    .iter()
67    .any(|needle| lower_attrs.contains(needle))
68}
69
70/// A `<style scoped>` block whose classes escape the component (`:global`,
71/// `:deep`, `::v-deep`) or whose used-set we cannot fully see (`@apply` pulls in
72/// classes by name) is skipped wholesale, conservatively.
73fn block_escapes_scope(body: &str) -> bool {
74    body.contains(":global")
75        || body.contains(":deep")
76        || body.contains("::v-deep")
77        || body.contains("/deep/")
78        || body.contains("@apply")
79}
80
81/// Returns class names defined in `<style scoped>` blocks of an SFC that appear
82/// nowhere else in the component (cleanup candidates), sorted. Returns an empty
83/// vec when the source has no analyzable scoped block.
84#[must_use]
85pub fn scoped_unused_classes(source: &str) -> Vec<String> {
86    let mut scoped_classes: FxHashSet<String> = FxHashSet::default();
87    // Byte ranges of every `<style>` block, blanked out of the search text so a
88    // class's own definition does not count as a use of itself.
89    let mut style_ranges: Vec<(usize, usize)> = Vec::new();
90
91    for caps in STYLE_BLOCK_RE.captures_iter(source) {
92        if let Some(whole) = caps.get(0) {
93            style_ranges.push((whole.start(), whole.end()));
94        }
95        let attrs = caps.name("attrs").map_or("", |m| m.as_str());
96        let body = caps.name("body").map_or("", |m| m.as_str());
97        if !has_scoped_attr(attrs) || has_non_css_lang(attrs) || block_escapes_scope(body) {
98            continue;
99        }
100        for export in extract_css_module_exports(body, false) {
101            if let ExportName::Named(name) = export.name {
102                scoped_classes.insert(name);
103            }
104        }
105    }
106
107    if scoped_classes.is_empty() {
108        return Vec::new();
109    }
110
111    let search = blank_ranges(source, &style_ranges);
112    let mut candidates: Vec<String> = scoped_classes
113        .into_iter()
114        .filter(|class| !class_token_appears(&search, class))
115        .collect();
116    candidates.sort_unstable();
117    candidates
118}
119
120/// Build a "virtual stylesheet" from an SFC's plain-CSS `<style>` blocks (any
121/// scoping). Each block body is placed at its real line in the SFC via blank-line
122/// padding, so CSS metric line numbers from `compute_css_analytics` map straight
123/// back onto the SFC. Returns `None` when the SFC has no plain-CSS `<style>`
124/// block (e.g. only `lang="scss"` blocks, which the CSS parser cannot read), so
125/// callers run the standard `.css` metric path on Vue/Svelte component styles.
126#[must_use]
127pub fn sfc_virtual_stylesheet(source: &str) -> Option<String> {
128    let mut out = String::new();
129    let mut current_line: usize = 1;
130    let mut found = false;
131    for caps in STYLE_BLOCK_RE.captures_iter(source) {
132        let attrs = caps.name("attrs").map_or("", |m| m.as_str());
133        if has_non_css_lang(attrs) {
134            continue;
135        }
136        let Some(body) = caps.name("body") else {
137            continue;
138        };
139        found = true;
140        let block_line = 1 + source[..body.start()]
141            .bytes()
142            .filter(|&b| b == b'\n')
143            .count();
144        while current_line < block_line {
145            out.push('\n');
146            current_line += 1;
147        }
148        out.push_str(body.as_str());
149        current_line += body.as_str().bytes().filter(|&b| b == b'\n').count();
150    }
151    found.then_some(out)
152}
153
154/// Build a virtual stylesheet from SFC preprocessor `<style>` blocks that the
155/// health layer can conservatively lower before CSS analytics.
156#[must_use]
157pub fn sfc_preprocessor_virtual_stylesheet(source: &str) -> Option<String> {
158    let mut out = String::new();
159    let mut current_line: usize = 1;
160    let mut found = false;
161    for caps in STYLE_BLOCK_RE.captures_iter(source) {
162        let attrs = caps.name("attrs").map_or("", |m| m.as_str());
163        if !has_preprocessor_lang(attrs) {
164            continue;
165        }
166        let Some(body) = caps.name("body") else {
167            continue;
168        };
169        found = true;
170        let block_line = 1 + source[..body.start()]
171            .bytes()
172            .filter(|&b| b == b'\n')
173            .count();
174        while current_line < block_line {
175            out.push('\n');
176            current_line += 1;
177        }
178        out.push_str(body.as_str());
179        current_line += body.as_str().bytes().filter(|&b| b == b'\n').count();
180    }
181    found.then_some(out)
182}
183
184/// Replace the given byte ranges in `source` with spaces (preserving length),
185/// so the returned string can be searched for class uses without the `<style>`
186/// blocks themselves matching.
187fn blank_ranges(source: &str, ranges: &[(usize, usize)]) -> String {
188    let mut out = source.as_bytes().to_vec();
189    for &(start, end) in ranges {
190        if start <= end && end <= out.len() {
191            for byte in &mut out[start..end] {
192                *byte = b' ';
193            }
194        }
195    }
196    // The blanked ranges align to `<style>`/`</style>` tag boundaries, which are
197    // ASCII, so the result stays valid UTF-8.
198    String::from_utf8(out).unwrap_or_else(|_| source.to_string())
199}
200
201/// Returns `true` when `name` appears as a whole class token in `text` (not as a
202/// substring of a longer identifier). `-` and `_` are treated as identifier
203/// characters so `foo` does not match inside `foo-bar`.
204fn class_token_appears(text: &str, name: &str) -> bool {
205    if name.is_empty() {
206        return false;
207    }
208    let bytes = text.as_bytes();
209    let len = name.len();
210    let mut from = 0;
211    while let Some(offset) = text[from..].find(name) {
212        let start = from + offset;
213        let end = start + len;
214        let before_ok = start == 0 || !is_identifier_byte(bytes[start - 1]);
215        let after_ok = end >= bytes.len() || !is_identifier_byte(bytes[end]);
216        if before_ok && after_ok {
217            return true;
218        }
219        from = start + 1;
220        if from >= text.len() {
221            break;
222        }
223    }
224    false
225}
226
227fn is_identifier_byte(byte: u8) -> bool {
228    byte.is_ascii_alphanumeric() || byte == b'_' || byte == b'-'
229}
230
231#[cfg(all(test, not(miri)))]
232mod tests {
233    use super::*;
234
235    #[test]
236    fn flags_unused_scoped_class() {
237        let dead = scoped_unused_classes(
238            "<template><div class=\"used\"></div></template>\n\
239             <style scoped>.used { color: red; } .dead { color: blue; }</style>",
240        );
241        assert_eq!(dead, vec!["dead".to_string()]);
242    }
243
244    #[test]
245    fn class_used_in_dynamic_binding_is_not_flagged() {
246        // The `active` token appears in the `:class` binding object, so it is a use.
247        let dead = scoped_unused_classes(
248            "<template><div :class=\"{ active: isActive }\"></div></template>\n\
249             <style scoped>.active { color: red; }</style>",
250        );
251        assert!(dead.is_empty(), "got {dead:?}");
252    }
253
254    #[test]
255    fn class_used_in_svelte_directive_is_not_flagged() {
256        let dead = scoped_unused_classes(
257            "<button class:selected={on}>x</button>\n\
258             <style>.selected { color: red; }</style>",
259        );
260        // No `scoped` attr on Svelte (styles are scoped by default), so this
261        // block is not analyzed and nothing is flagged.
262        assert!(dead.is_empty(), "got {dead:?}");
263    }
264
265    #[test]
266    fn class_referenced_in_script_is_not_flagged() {
267        let dead = scoped_unused_classes(
268            "<script>const c = \"highlight\";</script>\n\
269             <template><div :class=\"c\"></div></template>\n\
270             <style scoped>.highlight { color: red; }</style>",
271        );
272        assert!(dead.is_empty(), "got {dead:?}");
273    }
274
275    #[test]
276    fn global_selector_block_is_skipped() {
277        let dead = scoped_unused_classes(
278            "<template><div></div></template>\n\
279             <style scoped>:global(.x) { color: red; } .y { color: blue; }</style>",
280        );
281        assert!(dead.is_empty(), "blocks with :global are skipped wholesale");
282    }
283
284    #[test]
285    fn scss_scoped_block_is_skipped() {
286        let dead = scoped_unused_classes(
287            "<template><div></div></template>\n\
288             <style scoped lang=\"scss\">.dead { color: red; }</style>",
289        );
290        assert!(dead.is_empty(), "scss is not parsed");
291    }
292
293    #[test]
294    fn non_scoped_block_is_not_analyzed() {
295        let dead = scoped_unused_classes(
296            "<template><div></div></template>\n\
297             <style>.dead { color: red; }</style>",
298        );
299        assert!(dead.is_empty(), "only scoped blocks are analyzed");
300    }
301
302    #[test]
303    fn virtual_stylesheet_places_rules_at_sfc_lines() {
304        // The `.a` rule is on line 3 of the SFC; the virtual stylesheet must keep
305        // it on line 3 so metric line numbers map back onto the source.
306        let source = "<template>\n  <div/>\n</template>\n<style>\n.a { color: red; }\n</style>";
307        let vcss = super::sfc_virtual_stylesheet(source).expect("has a plain-CSS style block");
308        let line_of_a = 1 + vcss[..vcss.find(".a").unwrap()]
309            .bytes()
310            .filter(|&b| b == b'\n')
311            .count();
312        let sfc_line_of_a = 1 + source[..source.find(".a").unwrap()]
313            .bytes()
314            .filter(|&b| b == b'\n')
315            .count();
316        assert_eq!(line_of_a, sfc_line_of_a, "vcss={vcss:?}");
317    }
318
319    #[test]
320    fn virtual_stylesheet_none_without_plain_css_block() {
321        assert!(super::sfc_virtual_stylesheet("<template><div/></template>").is_none());
322        assert!(
323            super::sfc_virtual_stylesheet("<style lang=\"scss\">.a { .b {} }</style>").is_none(),
324            "scss-only SFC yields no virtual stylesheet"
325        );
326    }
327
328    #[test]
329    fn preprocessor_virtual_stylesheet_keeps_sfc_lines() {
330        let source =
331            "<template>\n  <div/>\n</template>\n<style lang=\"scss\">\n.a { .b {} }\n</style>";
332        let vcss = super::sfc_preprocessor_virtual_stylesheet(source)
333            .expect("has a preprocessor style block");
334        let line_of_a = 1 + vcss[..vcss.find(".a").unwrap()]
335            .bytes()
336            .filter(|&b| b == b'\n')
337            .count();
338        let sfc_line_of_a = 1 + source[..source.find(".a").unwrap()]
339            .bytes()
340            .filter(|&b| b == b'\n')
341            .count();
342        assert_eq!(line_of_a, sfc_line_of_a, "vcss={vcss:?}");
343    }
344
345    #[test]
346    fn hyphenated_class_token_boundary() {
347        // `.foo` is unused even though `foo-bar` appears in the template.
348        let dead = scoped_unused_classes(
349            "<template><div class=\"foo-bar\"></div></template>\n\
350             <style scoped>.foo { color: red; } .foo-bar { color: blue; }</style>",
351        );
352        assert_eq!(dead, vec!["foo".to_string()]);
353    }
354}
fallow_extract/sfc_css.rs

fallow_extract/
sfc_css.rs
