diff --git a/Cargo.lock b/Cargo.lock index d8fd1524a0c..1a4de63b6a9 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1571,6 +1571,8 @@ dependencies = [ "cfg-if", "countme", "indexmap", + "rome_js_parser", + "rome_js_syntax", "rome_rowan", "rustc-hash", "schemars", diff --git a/crates/rome_formatter/Cargo.toml b/crates/rome_formatter/Cargo.toml index fde1f730112..5c63d0c7b5b 100644 --- a/crates/rome_formatter/Cargo.toml +++ b/crates/rome_formatter/Cargo.toml @@ -18,5 +18,9 @@ schemars = { version = "0.8.10", optional = true } rustc-hash = "1.1.0" countme = "3.0.1" +[dev-dependencies] +rome_js_parser = { path = "../rome_js_parser"} +rome_js_syntax = { path = "../rome_js_syntax" } + [features] serde = ["dep:serde", "schemars", "rome_rowan/serde"] diff --git a/crates/rome_formatter/src/comments.rs b/crates/rome_formatter/src/comments.rs index 4c53a59b443..711f9a2f1e6 100644 --- a/crates/rome_formatter/src/comments.rs +++ b/crates/rome_formatter/src/comments.rs @@ -1,12 +1,90 @@ +//! Types for extracting and representing comments of a syntax tree. +//! +//! Most programming languages support comments allowing programmers to document their programs. Comments are different from other syntaxes because programming languages allow comments in almost any position, giving programmers great flexibility on where they can write comments: +//! +//! ```ignore +//! /** +//! * Documentation comment +//! */ +//! async /* comment */ function Test () // line comment +//! {/*inline*/} +//! ``` +//! +//! However, this flexibility makes formatting comments challenging because: +//! * The formatter must consistently place comments so that re-formatting the output yields the same result and does not create invalid syntax (line comments). +//! * It is essential that formatters place comments close to the syntax the programmer intended to document. However, the lack of rules regarding where comments are allowed and what syntax they document requires the use of heuristics to infer the documented syntax. +//! +//! This module strikes a balance between placing comments as closely as possible to their source location and reducing the complexity of formatting comments. It does so by associating comments per node rather than a token. This greatly reduces the combinations of possible comment positions but turns out to be, in practice, sufficiently precise to keep comments close to their source location. +//! +//! ## Node comments +//! +//! Comments are associated per node but get further distinguished on their location related to that node: +//! +//! ### Leading Comments +//! +//! A comment at the start of a node +//! +//! ```ignore +//! // Leading comment of the statement +//! console.log("test"); +//! +//! [/* leading comment of identifier */ a ]; +//! ``` +//! +//! ### Dangling Comments +//! +//! A comment that is neither at the start nor the end of a node +//! +//! ```ignore +//! [/* in between the brackets */ ]; +//! async /* between keywords */ function Test () {} +//! ``` +//! +//! ### Trailing Comments +//! +//! A comment at the end of a node +//! +//! ```ignore +//! [a /* trailing comment of a */, b, c]; +//! [ +//! a // trailing comment of a +//! ] +//! ``` +//! +//! ## Limitations +//! Limiting the placement of comments to leading, dangling, or trailing node comments reduces complexity inside the formatter but means, that the formatter's possibility of where comments can be formatted depends on the AST structure. +//! +//! For example, the continue statement in JavaScript is defined as: +//! +//! ```ungram +//! JsContinueStatement = +//! 'continue' +//! (label: 'ident')? +//! ';'? +//! ``` +//! +//! but a programmer may decide to add a comment in front or after the label: +//! +//! ```ignore +//! continue /* comment 1 */ label; +//! continue label /* comment 2*/; /* trailing */ +//! ``` +//! +//! Because all children of the `continue` statement are tokens, it is only possible to make the comments leading, dangling, or trailing comments of the `continue` statement. But this results in a loss of information as the formatting code can no longer distinguish if a comment appeared before or after the label and, thus, has to format them the same way. +//! +//! This hasn't shown to be a significant limitation today but the infrastructure could be extended to support a `label` on [`SourceComment`] that allows to further categorise comments. +//! + +mod builder; mod map; -use rome_rowan::{ - Direction, Language, SyntaxElement, SyntaxKind, SyntaxNode, SyntaxTriviaPieceComments, - WalkEvent, -}; +use self::{builder::CommentsBuilderVisitor, map::CommentsMap}; +use crate::{TextSize, TransformSourceMap}; +use rome_rowan::syntax::SyntaxElementKey; +use rome_rowan::{Language, SyntaxNode, SyntaxToken, SyntaxTriviaPieceComments}; +use rustc_hash::FxHashSet; #[cfg(debug_assertions)] use std::cell::RefCell; -use std::collections::HashSet; use std::rc::Rc; #[derive(Copy, Clone, Eq, PartialEq, Debug)] @@ -15,9 +93,7 @@ pub enum CommentKind { /// /// ## Examples /// - /// ### JavaScript: - /// - /// ```javascript + /// ```ignore /// a /* test */ /// ``` InlineBlock, @@ -26,8 +102,6 @@ pub enum CommentKind { /// /// ## Examples /// - /// ### JavaScript - /// /// ```javascript /// /* first line /// * more content on the second line @@ -39,111 +113,660 @@ pub enum CommentKind { /// /// ## Examples /// - /// ### JavaScript - /// - /// ```javascript + /// ```ignore /// a // test /// ``` Line, } +impl CommentKind { + pub const fn is_line(&self) -> bool { + matches!(self, CommentKind::Line) + } + + pub const fn is_block(&self) -> bool { + matches!(self, CommentKind::Block) + } + + pub const fn is_inline_block(&self) -> bool { + matches!(self, CommentKind::InlineBlock) + } + + /// Returns `true` for comments that can appear inline between any two tokens. + /// + /// ## Examples + /// + /// ```rust + /// use rome_formatter::comments::CommentKind; + /// + /// // Block and InlineBlock comments can appear inline + /// assert!(CommentKind::Block.is_inline()); + /// assert!(CommentKind::InlineBlock.is_inline()); + /// + /// // But not line comments + /// assert!(!CommentKind::Line.is_inline()) + /// ``` + pub const fn is_inline(&self) -> bool { + matches!(self, CommentKind::InlineBlock | CommentKind::Block) + } +} + +/// A comment in the source document. #[derive(Debug, Clone)] pub struct SourceComment { /// The number of lines appearing before this comment - lines_before: u32, + pub(crate) lines_before: u32, + + pub(crate) lines_after: u32, /// The comment piece - piece: SyntaxTriviaPieceComments, + pub(crate) piece: SyntaxTriviaPieceComments, + + /// The kind of the comment. + pub(crate) kind: CommentKind, } impl SourceComment { - /// Creates a new trailing comment. A trailing comment always has 0 lines before. - pub fn trailing(piece: SyntaxTriviaPieceComments) -> Self { - Self { - lines_before: 0, - piece, - } + /// Returns the underlining comment trivia piece + pub fn piece(&self) -> &SyntaxTriviaPieceComments { + &self.piece } - /// Creates a leading comment with the specified lines before - pub fn leading(piece: SyntaxTriviaPieceComments, lines_before: u32) -> Self { - Self { - lines_before, - piece, - } + /// The number of lines between this comment and the **previous** token or comment. + /// + /// # Examples + /// + /// ## Same line + /// + /// ```ignore + /// a // end of line + /// ``` + /// + /// Returns `0` because there's no line break between the token `a` and the comment. + /// + /// ## Own Line + /// + /// ```ignore + /// a; + /// + /// /* comment */ + /// ``` + /// + /// Returns `2` because there are two line breaks between the token `a` and the comment. + pub fn lines_before(&self) -> u32 { + self.lines_before } - /// Returns the underlining comment trivia piece + /// The number of line breaks right after this comment. + /// + /// # Examples + /// + /// ## End of line + /// + /// ```ignore + /// a; // comment + /// + /// b; + /// ``` + /// + /// Returns `2` because there are two line breaks between the comment and the token `b`. + /// + /// ## Same line + /// + /// ```ignore + /// a; + /// /* comment */ b; + /// ``` + /// + /// Returns `0` because there are no line breaks between the comment and the token `b`. + pub fn lines_after(&self) -> u32 { + self.lines_after + } + + /// The kind of the comment + pub fn kind(&self) -> CommentKind { + self.kind + } +} + +/// A comment decorated with additional information about its surrounding context in the source document. +/// +/// Used by [CommentStyle::place_comment] to determine if this should become a [leading](self#leading-comments), [dangling](self#dangling-comments), or [trailing](self#trailing-comments) comment. +#[derive(Debug, Clone)] +pub struct DecoratedComment { + enclosing: SyntaxNode, + preceding: Option>, + following: Option>, + following_token: SyntaxToken, + text_position: CommentTextPosition, + lines_before: u32, + lines_after: u32, + comment: SyntaxTriviaPieceComments, + kind: CommentKind, +} + +impl DecoratedComment { + /// The closest parent node that fully encloses the comment. + /// + /// A node encloses a comment when the comment is between two of its direct children (ignoring lists). + /// + /// # Examples + /// + /// ```ignore + /// [a, /* comment */ b] + /// ``` + /// + /// The enclosing node is the array expression and not the identifier `b` because + /// `a` and `b` are children of the array expression and `comment` is a comment between the two nodes. + pub fn enclosing_node(&self) -> &SyntaxNode { + &self.enclosing + } + + /// Returns the comment piece. pub fn piece(&self) -> &SyntaxTriviaPieceComments { - &self.piece + &self.comment } - /// Returns the number of lines before directly before this comment + /// Returns the node preceding the comment. + /// + /// The direct child node (ignoring lists) of the [`enclosing_node`](DecoratedComment::enclosing_node) that precedes this comment. + /// + /// Returns [None] if the [`enclosing_node`](DecoratedComment::enclosing_node) only consists of tokens or if + /// all preceding children of the [`enclosing_node`](DecoratedComment::enclosing_node) have been tokens. + /// + /// The Preceding node is guaranteed to be a sibling of [`following_node`](DecoratedComment::following_node). + /// + /// # Examples + /// + /// ## Preceding tokens only + /// + /// ```ignore + /// [/* comment */] + /// ``` + /// Returns [None] because the comment has no preceding node, only a preceding `[` token. + /// + /// ## Preceding node + /// + /// ```ignore + /// [a /* comment */, b] + /// ``` + /// + /// Returns `Some(a)` because `a` directly precedes the comment. + /// + /// ## Preceding token and node + /// + /// ```ignore + /// [a, /* comment */] + /// ``` + /// + /// Returns `Some(a)` because `a` is the preceding node of `comment`. The presence of the `,` token + /// doesn't change that. + pub fn preceding_node(&self) -> Option<&SyntaxNode> { + self.preceding.as_ref() + } + + /// Takes the [`preceding_node`](DecoratedComment::preceding_node) and replaces it with [None]. + fn take_preceding_node(&mut self) -> Option> { + self.preceding.take() + } + + /// Returns the node following the comment. + /// + /// The direct child node (ignoring lists) of the [`enclosing_node`](DecoratedComment::enclosing_node) that follows this comment. + /// + /// Returns [None] if the [`enclosing_node`](DecoratedComment::enclosing_node) only consists of tokens or if + /// all children children of the [`enclosing_node`](DecoratedComment::enclosing_node) following this comment are tokens. + /// + /// The following node is guaranteed to be a sibling of [`preceding_node`](DecoratedComment::preceding_node). + /// + /// # Examples + /// + /// ## Following tokens only + /// + /// ```ignore + /// [ /* comment */ ] + /// ``` + /// + /// Returns [None] because there's no node following the comment, only the `]` token. + /// + /// ## Following node + /// + /// ```ignore + /// [ /* comment */ a ] + /// ``` + /// + /// Returns `Some(a)` because `a` is the node directly following the comment. + /// + /// ## Following token and node + /// + /// ```ignore + /// async /* comment */ function test() {} + /// ``` + /// + /// Returns `Some(test)` because the `test` identifier is the first node following `comment`. + /// + /// ## Following parenthesized expression + /// + /// ```ignore + /// !( + /// a /* comment */ + /// ); + /// b + /// ``` + /// + /// Returns `None` because `comment` is enclosed inside the parenthesized expression and it has no children + /// following `/* comment */. + pub fn following_node(&self) -> Option<&SyntaxNode> { + self.following.as_ref() + } + + /// Takes the [`following_node`](DecoratedComment::following_node) and replaces it with [None]. + fn take_following_node(&mut self) -> Option> { + self.following.take() + } + + /// The number of line breaks between this comment and the **previous** token or comment. + /// + /// # Examples + /// + /// ## Same line + /// + /// ```ignore + /// a // end of line + /// ``` + /// + /// Returns `0` because there's no line break between the token `a` and the comment. + /// + /// ## Own Line + /// + /// ```ignore + /// a; + /// + /// /* comment */ + /// ``` + /// + /// Returns `2` because there are two line breaks between the token `a` and the comment. pub fn lines_before(&self) -> u32 { self.lines_before } + + /// The number of line breaks right after this comment. + /// + /// # Examples + /// + /// ## End of line + /// + /// ```ignore + /// a; // comment + /// + /// b; + /// ``` + /// + /// Returns `2` because there are two line breaks between the comment and the token `b`. + /// + /// ## Same line + /// + /// ```ignore + /// a; + /// /* comment */ b; + /// ``` + /// + /// Returns `0` because there are no line breaks between the comment and the token `b`. + pub fn lines_after(&self) -> u32 { + self.lines_after + } + + /// Returns the [CommentKind] of the comment. + pub fn kind(&self) -> CommentKind { + self.kind + } + + /// The position of the comment in the text. + pub fn text_position(&self) -> CommentTextPosition { + self.text_position + } + + /// The next token that comes after this comment. It is possible that other comments are between this comment + /// and the token. + /// + /// ```ignore + /// a /* comment */ /* other b */ + /// ``` + /// + /// The `following_token` for both comments is `b` because it's the token coming after the comments. + pub fn following_token(&self) -> &SyntaxToken { + &self.following_token + } } -impl CommentKind { - pub const fn is_line(&self) -> bool { - matches!(self, CommentKind::Line) +impl From> for SourceComment { + fn from(decorated: DecoratedComment) -> Self { + Self { + lines_before: decorated.lines_before, + lines_after: decorated.lines_after, + piece: decorated.comment, + kind: decorated.kind, + } } +} - pub const fn is_block(&self) -> bool { - matches!(self, CommentKind::Block) +/// The position of a comment in the source text. +#[derive(Debug, Copy, Clone, Eq, PartialEq)] +pub enum CommentTextPosition { + /// A comment that is on the same line as the preceding token and is separated by at least one line break from the following token. + /// + /// # Examples + /// + /// ## End of line + /// + /// ```ignore + /// a; /* this */ // or this + /// b; + /// ``` + /// + /// Both `/* this */` and `// or this` are end of line comments because both comments are separated by + /// at least one line break from the following token `b`. + /// + /// ## Own line + /// + /// ```ignore + /// a; + /// /* comment */ + /// b; + /// ``` + /// + /// This is not an end of line comment because it isn't on the same line as the preceding token `a`. + EndOfLine, + + /// A Comment that is separated by at least one line break from the preceding token. + /// + /// # Examples + /// + /// ```ignore + /// a; + /// /* comment */ /* or this */ + /// b; + /// ``` + /// + /// Both comments are own line comments because they are separated by one line break from the preceding + /// token `a`. + OwnLine, + + /// A comment that is placed on the same line as the preceding and following token. + /// + /// # Examples + /// + /// ```ignore + /// a /* comment */ + b + /// ``` + SameLine, +} + +impl CommentTextPosition { + pub const fn is_same_line(&self) -> bool { + matches!(self, CommentTextPosition::SameLine) } - pub const fn is_inline_block(&self) -> bool { - matches!(self, CommentKind::InlineBlock) + pub const fn is_own_line(&self) -> bool { + matches!(self, CommentTextPosition::OwnLine) } - /// Returns `true` for comments that can appear inline between any two tokens. + pub const fn is_end_of_line(&self) -> bool { + matches!(self, CommentTextPosition::EndOfLine) + } +} + +#[derive(Debug)] +pub enum CommentPlacement { + /// Makes `comment` a [leading comment](self#leading-comments) of `node`. + Leading { + node: SyntaxNode, + comment: SourceComment, + }, + /// Makes `comment` a [trailing comment](self#trailing-comments) of `node`. + Trailing { + node: SyntaxNode, + comment: SourceComment, + }, + + /// Makes `comment` a [dangling comment](self#dangling-comments) of `node`. + Dangling { + node: SyntaxNode, + comment: SourceComment, + }, + + /// Uses the default heuristic to determine the placement of the comment. + /// + /// # Same line comments + /// + /// Makes the comment a... + /// + /// * [trailing comment] of the [`preceding_node`] if both the [`following_node`] and [`preceding_node`] are not [None] + /// and the comment and [`preceding_node`] are only separated by a space (there's no token between the comment and [`preceding_node`]). + /// * [leading comment] of the [`following_node`] if the [`following_node`] is not [None] + /// * [trailing comment] of the [`preceding_node`] if the [`preceding_node`] is not [None] + /// * [dangling comment] of the [`enclosing_node`]. /// /// ## Examples + /// ### Comment with preceding and following nodes /// - /// ```rust - /// use rome_formatter::CommentKind; + /// ```ignore + /// [ + /// a, // comment + /// b + /// ] + /// ``` /// - /// // Block and InlineBlock comments can appear inline - /// assert!(CommentKind::Block.is_inline()); - /// assert!(CommentKind::InlineBlock.is_inline()); + /// The comment becomes a [trailing comment] of the node `a`. /// - /// // But not line comments - /// assert!(!CommentKind::Line.is_inline()) + /// ### Comment with preceding node only + /// + /// ```ignore + /// [ + /// a // comment + /// ] /// ``` - pub const fn is_inline(&self) -> bool { - matches!(self, CommentKind::InlineBlock | CommentKind::Block) + /// + /// The comment becomes a [trailing comment] of the node `a`. + /// + /// ### Comment with following node only + /// + /// ```ignore + /// [ // comment + /// b + /// ] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b`. + /// + /// ### Dangling comment + /// + /// ```ignore + /// [ // comment + /// ] + /// ``` + /// + /// The comment becomes a [dangling comment] of the enclosing array expression because both the [`preceding_node`] and [`following_node`] are [None]. + /// + /// # Own line comments + /// + /// Makes the comment a... + /// + /// * [leading comment] of the [`following_node`] if the [`following_node`] is not [None] + /// * or a [trailing comment] of the [`preceding_node`] if the [`preceding_node`] is not [None] + /// * or a [dangling comment] of the [`enclosing_node`]. + /// + /// ## Examples + /// + /// ### Comment with leading and preceding nodes + /// + /// ```ignore + /// [ + /// a, + /// // comment + /// b + /// ] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b`. + /// + /// ### Comment with preceding node only + /// + /// ```ignore + /// [ + /// a + /// // comment + /// ] + /// ``` + /// + /// The comment becomes a [trailing comment] of the node `a`. + /// + /// ### Comment with following node only + /// + /// ```ignore + /// [ + /// // comment + /// b + /// ] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b`. + /// + /// ### Dangling comment + /// + /// ```ignore + /// [ + /// // comment + /// ] + /// ``` + /// + /// The comment becomes a [dangling comment] of the array expression because both [`preceding_node`] and [`following_node`] are [None]. + /// + /// + /// # End of line comments + /// Makes the comment a... + /// + /// * [trailing comment] of the [`preceding_node`] if the [`preceding_node`] is not [None] + /// * or a [leading comment] of the [`following_node`] if the [`following_node`] is not [None] + /// * or a [dangling comment] of the [`enclosing_node`]. + /// + /// + /// ## Examples + /// + /// ### Comment with leading and preceding nodes + /// + /// ```ignore + /// [a /* comment */, b] + /// ``` + /// + /// The comment becomes a [trailing comment] of the node `a` because there's no token between the node `a` and the `comment`. + /// + /// ```ignore + /// [a, /* comment */ b] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b` because the node `a` and the comment are separated by a `,` token. + /// + /// ### Comment with preceding node only + /// + /// ```ignore + /// [a, /* last */ ] + /// ``` + /// + /// The comment becomes a [trailing comment] of the node `a` because the [`following_node`] is [None]. + /// + /// ### Comment with following node only + /// + /// ```ignore + /// [/* comment */ b] + /// ``` + /// + /// The comment becomes a [leading comment] of the node `b` because the [`preceding_node`] is [None] + /// + /// ### Dangling comment + /// + /// ```ignore + /// [/* comment*/] + /// ``` + /// + /// The comment becomes a [dangling comment] of the array expression because both [`preceding_node`] and [`following_node`] are [None]. + /// + /// [`preceding_node`]: DecoratedComment::preceding_node + /// [`following_node`]: DecoratedComment::following_node + /// [`enclosing_node`]: DecoratedComment::enclosing_node + /// [trailing comment]: self#trailing-comments + /// [leading comment]: self#leading-comments + /// [dangling comment]: self#dangling-comments + Default(DecoratedComment), +} + +impl CommentPlacement { + /// Makes `comment` a [leading comment](self#leading-comments) of `node`. + #[inline] + pub fn leading(node: SyntaxNode, comment: impl Into>) -> Self { + Self::Leading { + node, + comment: comment.into(), + } + } + + /// Makes `comment` a [dangling comment](self::dangling-comments) of `node`. + pub fn dangling(node: SyntaxNode, comment: impl Into>) -> Self { + Self::Dangling { + node, + comment: comment.into(), + } + } + + /// Makes `comment` a [trailing comment](self::trailing-comments) of `node`. + #[inline] + pub fn trailing(node: SyntaxNode, comment: impl Into>) -> Self { + Self::Trailing { + node, + comment: comment.into(), + } + } + + /// Returns the placement if it isn't [CommentPlacement::Default], otherwise calls `f` and returns the result. + #[inline] + pub fn or_else(self, f: F) -> Self + where + F: FnOnce(DecoratedComment) -> CommentPlacement, + { + match self { + CommentPlacement::Default(comment) => f(comment), + placement => placement, + } } } /// Defines how to format comments for a specific [Language]. -pub trait CommentStyle { +pub trait CommentStyle: Default { + type Language: Language; + /// Returns `true` if a comment with the given `text` is a `rome-ignore format:` suppression comment. - fn is_suppression(&self, text: &str) -> bool; + fn is_suppression(_text: &str) -> bool { + false + } /// Returns the (kind)[CommentKind] of the comment - fn get_comment_kind(&self, comment: &SyntaxTriviaPieceComments) -> CommentKind; - - /// Returns `true` if a token with the passed `kind` marks the start of a group. Common group tokens are: - /// * left parentheses: `(`, `[`, `{` - fn is_group_start_token(&self, kind: L::Kind) -> bool; - - /// Returns `true` if a token with the passed `kind` marks the end of a group. Common group end tokens are: - /// * right parentheses: `)`, `]`, `}` - /// * end of statement token: `;` - /// * element separator: `,` or `.`. - /// * end of file token: `EOF` - fn is_group_end_token(&self, kind: L::Kind) -> bool; + fn get_comment_kind(comment: &SyntaxTriviaPieceComments) -> CommentKind; + + /// Determines the placement of `comment`. + /// + /// The default implementation returns [CommentPlacement::Default]. + fn place_comment( + &self, + comment: DecoratedComment, + ) -> CommentPlacement { + CommentPlacement::Default(comment) + } } -/// Type that stores the comments of a tree and gives access to: -/// -/// * whether a node should be formatted as is because it has a leading suppression comment. -/// * a node's leading and trailing comments -/// * the dangling comments of a token +/// The comments of a syntax tree stored by node. /// /// Cloning `comments` is cheap as it only involves bumping a reference counter. -#[derive(Debug, Default, Clone)] +#[derive(Debug, Clone, Default)] pub struct Comments { /// The use of a [Rc] is necessary to achieve that [Comments] has a lifetime that is independent from the [crate::Formatter]. /// Having independent lifetimes is necessary to support the use case where a (formattable object)[crate::Format] @@ -164,67 +787,113 @@ pub struct Comments { } impl Comments { - /// Extracts all the suppressions from `root` and its child nodes. - pub fn from_node(root: &SyntaxNode, language: &FormatLanguage) -> Self + /// Extracts all the comments from `root` and its descendants nodes. + pub fn from_node