2 * @fileoverview Rule to require newlines before `return` statement
8 //------------------------------------------------------------------------------
10 //------------------------------------------------------------------------------
17 description: "require an empty line before `return` statements",
18 category: "Stylistic Issues",
20 url: "https://eslint.org/docs/rules/newline-before-return"
23 fixable: "whitespace",
26 expected: "Expected newline before return statement."
30 replacedBy: ["padding-line-between-statements"]
34 const sourceCode = context.getSourceCode();
36 //--------------------------------------------------------------------------
38 //--------------------------------------------------------------------------
41 * Tests whether node is preceded by supplied tokens
42 * @param {ASTNode} node node to check
43 * @param {Array} testTokens array of tokens to test against
44 * @returns {boolean} Whether or not the node is preceded by one of the supplied tokens
47 function isPrecededByTokens(node, testTokens) {
48 const tokenBefore = sourceCode.getTokenBefore(node);
50 return testTokens.some(token => tokenBefore.value === token);
54 * Checks whether node is the first node after statement or in block
55 * @param {ASTNode} node node to check
56 * @returns {boolean} Whether or not the node is the first node after statement or in block
59 function isFirstNode(node) {
60 const parentType = node.parent.type;
62 if (node.parent.body) {
63 return Array.isArray(node.parent.body)
64 ? node.parent.body[0] === node
65 : node.parent.body === node;
68 if (parentType === "IfStatement") {
69 return isPrecededByTokens(node, ["else", ")"]);
71 if (parentType === "DoWhileStatement") {
72 return isPrecededByTokens(node, ["do"]);
74 if (parentType === "SwitchCase") {
75 return isPrecededByTokens(node, [":"]);
77 return isPrecededByTokens(node, [")"]);
82 * Returns the number of lines of comments that precede the node
83 * @param {ASTNode} node node to check for overlapping comments
84 * @param {number} lineNumTokenBefore line number of previous token, to check for overlapping comments
85 * @returns {number} Number of lines of comments that precede the node
88 function calcCommentLines(node, lineNumTokenBefore) {
89 const comments = sourceCode.getCommentsBefore(node);
90 let numLinesComments = 0;
92 if (!comments.length) {
93 return numLinesComments;
96 comments.forEach(comment => {
99 if (comment.type === "Block") {
100 numLinesComments += comment.loc.end.line - comment.loc.start.line;
103 // avoid counting lines with inline comments twice
104 if (comment.loc.start.line === lineNumTokenBefore) {
108 if (comment.loc.end.line === node.loc.start.line) {
113 return numLinesComments;
117 * Returns the line number of the token before the node that is passed in as an argument
118 * @param {ASTNode} node The node to use as the start of the calculation
119 * @returns {number} Line number of the token before `node`
122 function getLineNumberOfTokenBefore(node) {
123 const tokenBefore = sourceCode.getTokenBefore(node);
124 let lineNumTokenBefore;
127 * Global return (at the beginning of a script) is a special case.
128 * If there is no token before `return`, then we expect no line
129 * break before the return. Comments are allowed to occupy lines
130 * before the global return, just no blank lines.
131 * Setting lineNumTokenBefore to zero in that case results in the
135 lineNumTokenBefore = tokenBefore.loc.end.line;
137 lineNumTokenBefore = 0; // global return at beginning of script
140 return lineNumTokenBefore;
144 * Checks whether node is preceded by a newline
145 * @param {ASTNode} node node to check
146 * @returns {boolean} Whether or not the node is preceded by a newline
149 function hasNewlineBefore(node) {
150 const lineNumNode = node.loc.start.line;
151 const lineNumTokenBefore = getLineNumberOfTokenBefore(node);
152 const commentLines = calcCommentLines(node, lineNumTokenBefore);
154 return (lineNumNode - lineNumTokenBefore - commentLines) > 1;
158 * Checks whether it is safe to apply a fix to a given return statement.
160 * The fix is not considered safe if the given return statement has leading comments,
161 * as we cannot safely determine if the newline should be added before or after the comments.
162 * For more information, see: https://github.com/eslint/eslint/issues/5958#issuecomment-222767211
163 * @param {ASTNode} node The return statement node to check.
164 * @returns {boolean} `true` if it can fix the node.
167 function canFix(node) {
168 const leadingComments = sourceCode.getCommentsBefore(node);
169 const lastLeadingComment = leadingComments[leadingComments.length - 1];
170 const tokenBefore = sourceCode.getTokenBefore(node);
172 if (leadingComments.length === 0) {
177 * if the last leading comment ends in the same line as the previous token and
178 * does not share a line with the `return` node, we can consider it safe to fix.
185 if (lastLeadingComment.loc.end.line === tokenBefore.loc.end.line &&
186 lastLeadingComment.loc.end.line !== node.loc.start.line) {
193 //--------------------------------------------------------------------------
195 //--------------------------------------------------------------------------
198 ReturnStatement(node) {
199 if (!isFirstNode(node) && !hasNewlineBefore(node)) {
202 messageId: "expected",
205 const tokenBefore = sourceCode.getTokenBefore(node);
206 const newlines = node.loc.start.line === tokenBefore.loc.end.line ? "\n\n" : "\n";
208 return fixer.insertTextBefore(node, newlines);