Skip to main content

foundry_common/comments/
mod.rs

1use crate::iter::IterDelimited;
2use inline_config::InlineConfigItem;
3use solar::parse::{
4    ast::{CommentKind, Span},
5    interface::{BytePos, CharPos, SourceMap, source_map::SourceFile},
6    lexer::token::RawTokenKind as TokenKind,
7};
8use std::fmt;
9
10mod comment;
11pub use comment::{Comment, CommentStyle};
12
13pub mod inline_config;
14
15#[derive(Default)]
16pub struct Comments {
17    comments: std::collections::VecDeque<Comment>,
18}
19
20impl fmt::Debug for Comments {
21    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
22        f.write_str("Comments")?;
23        f.debug_list().entries(self.iter()).finish()
24    }
25}
26
27impl Comments {
28    pub fn new(
29        sf: &SourceFile,
30        _sm: &SourceMap,
31        normalize_cmnts: bool,
32        group_cmnts: bool,
33        tab_width: Option<usize>,
34    ) -> Self {
35        let gatherer = CommentGatherer::new(sf, normalize_cmnts, tab_width).gather();
36
37        Self {
38            comments: if group_cmnts { gatherer.group().into() } else { gatherer.comments.into() },
39        }
40    }
41
42    pub fn peek(&self) -> Option<&Comment> {
43        self.comments.front()
44    }
45
46    #[allow(clippy::should_implement_trait)]
47    pub fn next(&mut self) -> Option<Comment> {
48        self.comments.pop_front()
49    }
50
51    pub fn iter(&self) -> impl Iterator<Item = &Comment> {
52        self.comments.iter()
53    }
54
55    /// Adds a new comment at the beginning of the list.
56    ///
57    /// Should only be used when comments are gathered scattered, and must be manually sorted.
58    ///
59    /// **WARNING:** This struct works under the assumption that comments are always sorted by
60    /// ascending span position. It is the caller's responsibility to ensure that this premise
61    /// always holds true.
62    pub fn push_front(&mut self, cmnt: Comment) {
63        self.comments.push_front(cmnt)
64    }
65
66    /// Finds the first trailing comment on the same line as `span_pos`, allowing for `Mixed`
67    /// style comments to appear before it.
68    ///
69    /// Returns the comment and its index in the buffer.
70    pub fn peek_trailing(
71        &self,
72        sm: &SourceMap,
73        span_pos: BytePos,
74        next_pos: Option<BytePos>,
75    ) -> Option<(&Comment, usize)> {
76        self.peek_trailing_with(span_pos, next_pos, |pos| {
77            sm.lookup_line(pos).ok().map(|line| line.line)
78        })
79    }
80
81    /// Finds a trailing comment as in [`Self::peek_trailing`], using a known source file.
82    ///
83    /// All comment positions and `span_pos` must belong to `file`.
84    pub fn peek_trailing_in_file(
85        &self,
86        file: &SourceFile,
87        span_pos: BytePos,
88        next_pos: Option<BytePos>,
89    ) -> Option<(&Comment, usize)> {
90        self.peek_trailing_with(span_pos, next_pos, |pos| {
91            file.lookup_line(file.relative_position(pos))
92        })
93    }
94
95    fn peek_trailing_with(
96        &self,
97        span_pos: BytePos,
98        next_pos: Option<BytePos>,
99        line_at: impl Fn(BytePos) -> Option<usize>,
100    ) -> Option<(&Comment, usize)> {
101        self.comments.front()?;
102        let span_line = line_at(span_pos);
103        for (i, cmnt) in self.iter().enumerate() {
104            // If we have moved to the next line, we can stop.
105            let comment_line = line_at(cmnt.pos());
106            if comment_line != span_line {
107                break;
108            }
109
110            // The comment must start after the given span position.
111            if cmnt.pos() < span_pos {
112                continue;
113            }
114
115            // The comment must be before the next element.
116            if cmnt.pos() >= next_pos.unwrap_or_else(|| cmnt.pos() + BytePos(1)) {
117                break;
118            }
119
120            // Stop when we find a trailing or a non-mixed comment
121            match cmnt.style {
122                CommentStyle::Mixed => {}
123                CommentStyle::Trailing => return Some((cmnt, i)),
124                _ => break,
125            }
126        }
127        None
128    }
129}
130
131struct CommentGatherer<'ast> {
132    sf: &'ast SourceFile,
133    text: &'ast str,
134    start_bpos: BytePos,
135    pos: usize,
136    comments: Vec<Comment>,
137    code_to_the_left: bool,
138    disabled_block_depth: usize,
139    /// A nonzero baseline keeps normalization disabled regardless of formatting directives.
140    min_disabled_block_depth: usize,
141    tab_width: Option<usize>,
142}
143
144impl<'ast> CommentGatherer<'ast> {
145    fn new(sf: &'ast SourceFile, normalize_cmnts: bool, tab_width: Option<usize>) -> Self {
146        let min_disabled_block_depth = if normalize_cmnts { 0 } else { 1 };
147        Self {
148            sf,
149            text: sf.src.as_str(),
150            start_bpos: sf.start_pos,
151            pos: 0,
152            comments: Vec::new(),
153            code_to_the_left: false,
154            disabled_block_depth: min_disabled_block_depth,
155            min_disabled_block_depth,
156            tab_width,
157        }
158    }
159
160    /// Consumes the gatherer and returns the collected comments.
161    fn gather(mut self) -> Self {
162        for token in solar::parse::Cursor::new(&self.text[self.pos..]) {
163            self.process_token(token);
164        }
165        self
166    }
167
168    /// Post-processes a list of comments to group consecutive comments.
169    ///
170    /// Necessary for properly indenting multi-line trailing comments, which would
171    /// otherwise be parsed as a `Trailing` followed by several `Isolated`.
172    fn group(self) -> Vec<Comment> {
173        let mut processed = Vec::new();
174        let mut cursor = self.comments.into_iter().peekable();
175
176        while let Some(mut current) = cursor.next() {
177            if current.kind == CommentKind::Line
178                && (current.style.is_trailing() || current.style.is_isolated())
179                && current.format_directives().next().is_none()
180            {
181                let mut ref_line =
182                    self.sf.lookup_line(self.sf.relative_position(current.span.hi())).unwrap();
183                while let Some(next_comment) = cursor.peek() {
184                    if !next_comment.style.is_isolated()
185                        || next_comment.kind != CommentKind::Line
186                        || next_comment.is_doc != current.is_doc
187                        || next_comment.format_directives().next().is_some()
188                        || ref_line + 1
189                            != self
190                                .sf
191                                .lookup_line(self.sf.relative_position(next_comment.span.lo()))
192                                .unwrap()
193                    {
194                        break;
195                    }
196
197                    let next_to_merge = cursor.next().unwrap();
198                    current.lines.extend(next_to_merge.lines);
199                    current.span = current.span.to(next_to_merge.span);
200                    ref_line += 1;
201                }
202            }
203
204            processed.push(current);
205        }
206
207        processed
208    }
209
210    /// Creates a `Span` relative to the source file's start position.
211    fn make_span(&self, range: std::ops::Range<usize>) -> Span {
212        Span::new(self.start_bpos + range.start as u32, self.start_bpos + range.end as u32)
213    }
214
215    /// Processes a single token from the source.
216    fn process_token(&mut self, token: solar::parse::lexer::token::RawToken) {
217        let token_range = self.pos..self.pos + token.len as usize;
218        let span = self.make_span(token_range.clone());
219        let token_text = &self.text[token_range];
220
221        #[allow(clippy::collapsible_match)]
222        match token.kind {
223            TokenKind::Whitespace => {
224                if let Some(mut idx) = token_text.find('\n') {
225                    self.code_to_the_left = false;
226
227                    while let Some(next_newline) = token_text[idx + 1..].find('\n') {
228                        idx += 1 + next_newline;
229                        let pos = self.pos + idx;
230                        self.comments.push(Comment {
231                            is_doc: false,
232                            kind: CommentKind::Line,
233                            style: CommentStyle::BlankLine,
234                            lines: vec![],
235                            span: self.make_span(pos..pos),
236                        });
237                        // If not disabled, early-exit as we want only a single blank line.
238                        if self.disabled_block_depth == 0 {
239                            break;
240                        }
241                    }
242                }
243            }
244            TokenKind::BlockComment { is_doc, .. } => {
245                let code_to_the_right = !matches!(
246                    self.text[self.pos + token.len as usize..].chars().next(),
247                    Some('\r' | '\n')
248                );
249                let style = match (self.code_to_the_left, code_to_the_right) {
250                    (_, true) => CommentStyle::Mixed,
251                    (false, false) => CommentStyle::Isolated,
252                    (true, false) => CommentStyle::Trailing,
253                };
254                let kind = CommentKind::Block;
255                let mut comment =
256                    Comment { is_doc, kind, style, lines: vec![token_text.into()], span };
257                let disabled = self.update_disabled_block_depth(&comment);
258
259                // Measure the opening column, expanding tabs for non-doc comments.
260                let pos_in_file = self.start_bpos + BytePos(self.pos as u32);
261                let line_begin_in_file = line_begin_pos(self.sf, pos_in_file);
262                let line_begin_pos = (line_begin_in_file - self.start_bpos).to_usize();
263                let tab_width = if is_doc { 1 } else { self.tab_width.unwrap_or(1) };
264                let mut col =
265                    CharPos(estimate_line_width(&self.text[line_begin_pos..self.pos], tab_width));
266
267                // To preserve alignment in multi-line non-doc comments, normalize the block based
268                // on its least-indented line.
269                if !is_doc && token_text.contains('\n') {
270                    col = token_text.lines().skip(1).fold(col, |min, line| {
271                        if line.is_empty() {
272                            return min;
273                        }
274                        std::cmp::min(
275                            CharPos(estimate_line_width(
276                                &line[..line.len() - line.trim_start().len()],
277                                tab_width,
278                            )),
279                            min,
280                        )
281                    })
282                };
283
284                if !disabled {
285                    comment.lines = self.split_block_comment_into_lines(token_text, is_doc, col);
286                }
287                self.comments.push(comment)
288            }
289            TokenKind::LineComment { is_doc } => {
290                let mut comment = Comment {
291                    is_doc,
292                    kind: CommentKind::Line,
293                    style: if self.code_to_the_left {
294                        CommentStyle::Trailing
295                    } else {
296                        CommentStyle::Isolated
297                    },
298                    lines: vec![token_text.into()],
299                    span,
300                };
301                self.update_disabled_block_depth(&comment);
302                if self.disabled_block_depth == 0 {
303                    comment.lines[0].truncate(token_text.trim_end().len());
304                }
305                self.comments.push(comment);
306            }
307            _ => {
308                self.code_to_the_left = true;
309            }
310        }
311        self.pos += token.len as usize;
312    }
313
314    /// Splits a block comment into lines, ensuring that each line is properly formatted.
315    fn split_block_comment_into_lines(
316        &self,
317        text: &str,
318        is_doc: bool,
319        col: CharPos,
320    ) -> Vec<String> {
321        let mut res: Vec<String> = vec![];
322        let mut lines = text.lines();
323        if let Some(line) = lines.next() {
324            let line = line.trim_end();
325            // Ensure first line of a doc comment only has the `/**` decorator
326            if is_doc && let Some((_, second)) = line.split_once("/**") {
327                res.push("/**".to_string());
328                if !second.trim().is_empty() {
329                    let line = normalize_block_comment_ws(second, col).trim_end();
330                    // Ensure last line of a doc comment only has the `*/` decorator
331                    if let Some((first, _)) = line.split_once("*/") {
332                        if !first.trim().is_empty() {
333                            res.push(format_doc_block_comment(first.trim_end(), self.tab_width));
334                        }
335                        res.push(" */".to_string());
336                    } else {
337                        res.push(format_doc_block_comment(line.trim_end(), self.tab_width));
338                    }
339                }
340            } else {
341                res.push(line.to_string());
342            }
343        }
344
345        for (pos, line) in lines.delimited() {
346            let indent_end = line.len() - line.trim_start().len();
347            let mut expanded = String::new();
348            let line = if !is_doc
349                && let Some(tab_width) = self.tab_width
350                && line[..indent_end].contains('\t')
351            {
352                // Trim tab indentation in the same display columns used by the printer.
353                expanded.extend(std::iter::repeat_n(
354                    ' ',
355                    estimate_line_width(&line[..indent_end], tab_width),
356                ));
357                expanded.push_str(&line[indent_end..]);
358                expanded.as_str()
359            } else {
360                line
361            };
362            let line = normalize_block_comment_ws(line, col).trim_end().to_string();
363            if !is_doc {
364                res.push(line);
365                continue;
366            }
367            if pos.is_last {
368                // Ensure last line of a doc comment only has the `*/` decorator
369                if let Some((first, _)) = line.split_once("*/")
370                    && !first.trim().is_empty()
371                {
372                    res.push(format_doc_block_comment(first.trim_end(), self.tab_width));
373                }
374                res.push(" */".to_string());
375            } else {
376                res.push(format_doc_block_comment(&line, self.tab_width));
377            }
378        }
379        res
380    }
381
382    /// Tracks disabled blocks and returns whether the comment overlaps a disabled block.
383    fn update_disabled_block_depth(&mut self, comment: &Comment) -> bool {
384        let mut disabled = self.disabled_block_depth != 0;
385        for item in comment.format_directives() {
386            match item {
387                Ok(InlineConfigItem::DisableStart(())) => {
388                    self.disabled_block_depth += 1;
389                    disabled = true;
390                }
391                Ok(InlineConfigItem::DisableEnd(()))
392                    if self.disabled_block_depth > self.min_disabled_block_depth =>
393                {
394                    self.disabled_block_depth -= 1;
395                }
396                _ => {}
397            }
398        }
399        disabled
400    }
401}
402
403/// Returns `None` if the first `col` chars of `s` contain a non-whitespace char.
404/// Otherwise returns `Some(k)` where `k` is first char offset after that leading
405/// whitespace. Note that `k` may be outside bounds of `s`.
406fn all_whitespace(s: &str, col: CharPos) -> Option<usize> {
407    let mut idx = 0;
408    for (i, ch) in s.char_indices().take(col.to_usize()) {
409        if !ch.is_whitespace() {
410            return None;
411        }
412        idx = i + ch.len_utf8();
413    }
414    Some(idx)
415}
416
417/// Returns `Some(k)` where `k` is the byte offset of the first non-whitespace char. Returns `k = 0`
418/// if `s` starts with a non-whitespace char. If `s` only contains whitespaces, returns `None`.
419fn first_non_whitespace(s: &str) -> Option<usize> {
420    let mut len = 0;
421    for (i, ch) in s.char_indices() {
422        if ch.is_whitespace() {
423            len = ch.len_utf8()
424        } else {
425            return if i == 0 { Some(0) } else { Some(i + 1 - len) };
426        }
427    }
428    None
429}
430
431/// Returns a slice of `s` with a whitespace prefix removed based on `col`. If the first `col` chars
432/// of `s` are all whitespace, returns a slice starting after that prefix.
433fn normalize_block_comment_ws(s: &str, col: CharPos) -> &str {
434    let len = s.len();
435    if let Some(col) = all_whitespace(s, col) {
436        return if col < len { &s[col..] } else { "" };
437    }
438    if let Some(col) = first_non_whitespace(s) {
439        return &s[col..];
440    }
441    s
442}
443
444/// Formats a doc block comment line so that they have the ` *` decorator.
445fn format_doc_block_comment(line: &str, tab_width: Option<usize>) -> String {
446    if line.is_empty() {
447        return (" *").to_string();
448    }
449
450    if let Some((_, rest_of_line)) = line.split_once('*') {
451        if rest_of_line.is_empty() {
452            (" *").to_string()
453        } else if let Some(tab_width) = tab_width {
454            let mut normalized = String::from(" *");
455            line_with_tabs(
456                &mut normalized,
457                rest_of_line,
458                tab_width,
459                Some(Consolidation::MinOneTab),
460            );
461            normalized
462        } else {
463            format!(" *{rest_of_line}",)
464        }
465    } else if let Some(tab_width) = tab_width {
466        let mut normalized = String::from(" *\t");
467        line_with_tabs(&mut normalized, line, tab_width, Some(Consolidation::WithoutSpaces));
468        normalized
469    } else {
470        format!(" * {line}")
471    }
472}
473
474pub enum Consolidation {
475    MinOneTab,
476    WithoutSpaces,
477}
478
479/// Normalizes the leading whitespace of a string slice according to a given tab width.
480///
481/// It aggregates and converts leading whitespace (spaces and tabs) into a representation that
482/// maximizes the amount of tabs.
483pub fn line_with_tabs(
484    output: &mut String,
485    line: &str,
486    tab_width: usize,
487    strategy: Option<Consolidation>,
488) {
489    // Find the end of the leading whitespace (any sequence of spaces and tabs)
490    let first_non_ws = line.find(|c| c != ' ' && c != '\t').unwrap_or(line.len());
491    let (leading_ws, rest_of_line) = line.split_at(first_non_ws);
492
493    // Compute its equivalent length and derive the required amount of tabs and spaces
494    let total_width =
495        leading_ws.chars().fold(0, |width, c| width + if c == ' ' { 1 } else { tab_width });
496    let (mut num_tabs, mut num_spaces) = (total_width / tab_width, total_width % tab_width);
497
498    // Adjust based on the desired config
499    match strategy {
500        Some(Consolidation::MinOneTab) => {
501            if num_tabs == 0 && num_spaces != 0 {
502                (num_tabs, num_spaces) = (1, 0);
503            } else if num_spaces != 0 {
504                (num_tabs, num_spaces) = (num_tabs + 1, 0);
505            }
506        }
507        Some(Consolidation::WithoutSpaces) if num_spaces != 0 => {
508            (num_tabs, num_spaces) = (num_tabs + 1, 0);
509        }
510        _ => (),
511    };
512
513    // Append the normalized indentation and the rest of the line to the output
514    output.extend(std::iter::repeat_n('\t', num_tabs));
515    output.extend(std::iter::repeat_n(' ', num_spaces));
516    output.push_str(rest_of_line);
517}
518
519/// Estimates the display width of a string, accounting for tabs.
520pub fn estimate_line_width(line: &str, tab_width: usize) -> usize {
521    line.chars().fold(0, |width, c| width + if c == '\t' { tab_width } else { 1 })
522}
523
524/// Returns the `BytePos` of the beginning of the current line.
525fn line_begin_pos(sf: &SourceFile, pos: BytePos) -> BytePos {
526    let pos = sf.relative_position(pos);
527    let line_index = sf.lookup_line(pos).unwrap();
528    let line_start_pos = sf.lines()[line_index];
529    sf.absolute_position(line_start_pos)
530}