| /** |
| * @fileoverview Abstraction of JavaScript source code. |
| * @author Nicholas C. Zakas |
| */ |
| "use strict"; |
| |
| //------------------------------------------------------------------------------ |
| // Requirements |
| //------------------------------------------------------------------------------ |
| |
| const |
| { isCommentToken } = require("eslint-utils"), |
| TokenStore = require("./token-store"), |
| astUtils = require("../shared/ast-utils"), |
| Traverser = require("../shared/traverser"), |
| lodash = require("lodash"); |
| |
| //------------------------------------------------------------------------------ |
| // Private |
| //------------------------------------------------------------------------------ |
| |
| /** |
| * Validates that the given AST has the required information. |
| * @param {ASTNode} ast The Program node of the AST to check. |
| * @throws {Error} If the AST doesn't contain the correct information. |
| * @returns {void} |
| * @private |
| */ |
| function validate(ast) { |
| if (!ast.tokens) { |
| throw new Error("AST is missing the tokens array."); |
| } |
| |
| if (!ast.comments) { |
| throw new Error("AST is missing the comments array."); |
| } |
| |
| if (!ast.loc) { |
| throw new Error("AST is missing location information."); |
| } |
| |
| if (!ast.range) { |
| throw new Error("AST is missing range information"); |
| } |
| } |
| |
| /** |
| * Check to see if its a ES6 export declaration. |
| * @param {ASTNode} astNode An AST node. |
| * @returns {boolean} whether the given node represents an export declaration. |
| * @private |
| */ |
| function looksLikeExport(astNode) { |
| return astNode.type === "ExportDefaultDeclaration" || astNode.type === "ExportNamedDeclaration" || |
| astNode.type === "ExportAllDeclaration" || astNode.type === "ExportSpecifier"; |
| } |
| |
| /** |
| * Merges two sorted lists into a larger sorted list in O(n) time. |
| * @param {Token[]} tokens The list of tokens. |
| * @param {Token[]} comments The list of comments. |
| * @returns {Token[]} A sorted list of tokens and comments. |
| * @private |
| */ |
| function sortedMerge(tokens, comments) { |
| const result = []; |
| let tokenIndex = 0; |
| let commentIndex = 0; |
| |
| while (tokenIndex < tokens.length || commentIndex < comments.length) { |
| if (commentIndex >= comments.length || tokenIndex < tokens.length && tokens[tokenIndex].range[0] < comments[commentIndex].range[0]) { |
| result.push(tokens[tokenIndex++]); |
| } else { |
| result.push(comments[commentIndex++]); |
| } |
| } |
| |
| return result; |
| } |
| |
| //------------------------------------------------------------------------------ |
| // Public Interface |
| //------------------------------------------------------------------------------ |
| |
| class SourceCode extends TokenStore { |
| |
| /** |
| * Represents parsed source code. |
| * @param {string|Object} textOrConfig - The source code text or config object. |
| * @param {string} textOrConfig.text - The source code text. |
| * @param {ASTNode} textOrConfig.ast - The Program node of the AST representing the code. This AST should be created from the text that BOM was stripped. |
| * @param {Object|null} textOrConfig.parserServices - The parser services. |
| * @param {ScopeManager|null} textOrConfig.scopeManager - The scope of this source code. |
| * @param {Object|null} textOrConfig.visitorKeys - The visitor keys to traverse AST. |
| * @param {ASTNode} [astIfNoConfig] - The Program node of the AST representing the code. This AST should be created from the text that BOM was stripped. |
| * @constructor |
| */ |
| constructor(textOrConfig, astIfNoConfig) { |
| let text, ast, parserServices, scopeManager, visitorKeys; |
| |
| // Process overloading. |
| if (typeof textOrConfig === "string") { |
| text = textOrConfig; |
| ast = astIfNoConfig; |
| } else if (typeof textOrConfig === "object" && textOrConfig !== null) { |
| text = textOrConfig.text; |
| ast = textOrConfig.ast; |
| parserServices = textOrConfig.parserServices; |
| scopeManager = textOrConfig.scopeManager; |
| visitorKeys = textOrConfig.visitorKeys; |
| } |
| |
| validate(ast); |
| super(ast.tokens, ast.comments); |
| |
| /** |
| * The flag to indicate that the source code has Unicode BOM. |
| * @type boolean |
| */ |
| this.hasBOM = (text.charCodeAt(0) === 0xFEFF); |
| |
| /** |
| * The original text source code. |
| * BOM was stripped from this text. |
| * @type string |
| */ |
| this.text = (this.hasBOM ? text.slice(1) : text); |
| |
| /** |
| * The parsed AST for the source code. |
| * @type ASTNode |
| */ |
| this.ast = ast; |
| |
| /** |
| * The parser services of this source code. |
| * @type {Object} |
| */ |
| this.parserServices = parserServices || {}; |
| |
| /** |
| * The scope of this source code. |
| * @type {ScopeManager|null} |
| */ |
| this.scopeManager = scopeManager || null; |
| |
| /** |
| * The visitor keys to traverse AST. |
| * @type {Object} |
| */ |
| this.visitorKeys = visitorKeys || Traverser.DEFAULT_VISITOR_KEYS; |
| |
| // Check the source text for the presence of a shebang since it is parsed as a standard line comment. |
| const shebangMatched = this.text.match(astUtils.shebangPattern); |
| const hasShebang = shebangMatched && ast.comments.length && ast.comments[0].value === shebangMatched[1]; |
| |
| if (hasShebang) { |
| ast.comments[0].type = "Shebang"; |
| } |
| |
| this.tokensAndComments = sortedMerge(ast.tokens, ast.comments); |
| |
| /** |
| * The source code split into lines according to ECMA-262 specification. |
| * This is done to avoid each rule needing to do so separately. |
| * @type string[] |
| */ |
| this.lines = []; |
| this.lineStartIndices = [0]; |
| |
| const lineEndingPattern = astUtils.createGlobalLinebreakMatcher(); |
| let match; |
| |
| /* |
| * Previously, this was implemented using a regex that |
| * matched a sequence of non-linebreak characters followed by a |
| * linebreak, then adding the lengths of the matches. However, |
| * this caused a catastrophic backtracking issue when the end |
| * of a file contained a large number of non-newline characters. |
| * To avoid this, the current implementation just matches newlines |
| * and uses match.index to get the correct line start indices. |
| */ |
| while ((match = lineEndingPattern.exec(this.text))) { |
| this.lines.push(this.text.slice(this.lineStartIndices[this.lineStartIndices.length - 1], match.index)); |
| this.lineStartIndices.push(match.index + match[0].length); |
| } |
| this.lines.push(this.text.slice(this.lineStartIndices[this.lineStartIndices.length - 1])); |
| |
| // Cache for comments found using getComments(). |
| this._commentCache = new WeakMap(); |
| |
| // don't allow modification of this object |
| Object.freeze(this); |
| Object.freeze(this.lines); |
| } |
| |
| /** |
| * Split the source code into multiple lines based on the line delimiters. |
| * @param {string} text Source code as a string. |
| * @returns {string[]} Array of source code lines. |
| * @public |
| */ |
| static splitLines(text) { |
| return text.split(astUtils.createGlobalLinebreakMatcher()); |
| } |
| |
| /** |
| * Gets the source code for the given node. |
| * @param {ASTNode=} node The AST node to get the text for. |
| * @param {int=} beforeCount The number of characters before the node to retrieve. |
| * @param {int=} afterCount The number of characters after the node to retrieve. |
| * @returns {string} The text representing the AST node. |
| * @public |
| */ |
| getText(node, beforeCount, afterCount) { |
| if (node) { |
| return this.text.slice(Math.max(node.range[0] - (beforeCount || 0), 0), |
| node.range[1] + (afterCount || 0)); |
| } |
| return this.text; |
| } |
| |
| /** |
| * Gets the entire source text split into an array of lines. |
| * @returns {Array} The source text as an array of lines. |
| * @public |
| */ |
| getLines() { |
| return this.lines; |
| } |
| |
| /** |
| * Retrieves an array containing all comments in the source code. |
| * @returns {ASTNode[]} An array of comment nodes. |
| * @public |
| */ |
| getAllComments() { |
| return this.ast.comments; |
| } |
| |
| /** |
| * Gets all comments for the given node. |
| * @param {ASTNode} node The AST node to get the comments for. |
| * @returns {Object} An object containing a leading and trailing array |
| * of comments indexed by their position. |
| * @public |
| */ |
| getComments(node) { |
| if (this._commentCache.has(node)) { |
| return this._commentCache.get(node); |
| } |
| |
| const comments = { |
| leading: [], |
| trailing: [] |
| }; |
| |
| /* |
| * Return all comments as leading comments of the Program node when |
| * there is no executable code. |
| */ |
| if (node.type === "Program") { |
| if (node.body.length === 0) { |
| comments.leading = node.comments; |
| } |
| } else { |
| |
| /* |
| * Return comments as trailing comments of nodes that only contain |
| * comments (to mimic the comment attachment behavior present in Espree). |
| */ |
| if ((node.type === "BlockStatement" || node.type === "ClassBody") && node.body.length === 0 || |
| node.type === "ObjectExpression" && node.properties.length === 0 || |
| node.type === "ArrayExpression" && node.elements.length === 0 || |
| node.type === "SwitchStatement" && node.cases.length === 0 |
| ) { |
| comments.trailing = this.getTokens(node, { |
| includeComments: true, |
| filter: isCommentToken |
| }); |
| } |
| |
| /* |
| * Iterate over tokens before and after node and collect comment tokens. |
| * Do not include comments that exist outside of the parent node |
| * to avoid duplication. |
| */ |
| let currentToken = this.getTokenBefore(node, { includeComments: true }); |
| |
| while (currentToken && isCommentToken(currentToken)) { |
| if (node.parent && (currentToken.start < node.parent.start)) { |
| break; |
| } |
| comments.leading.push(currentToken); |
| currentToken = this.getTokenBefore(currentToken, { includeComments: true }); |
| } |
| |
| comments.leading.reverse(); |
| |
| currentToken = this.getTokenAfter(node, { includeComments: true }); |
| |
| while (currentToken && isCommentToken(currentToken)) { |
| if (node.parent && (currentToken.end > node.parent.end)) { |
| break; |
| } |
| comments.trailing.push(currentToken); |
| currentToken = this.getTokenAfter(currentToken, { includeComments: true }); |
| } |
| } |
| |
| this._commentCache.set(node, comments); |
| return comments; |
| } |
| |
| /** |
| * Retrieves the JSDoc comment for a given node. |
| * @param {ASTNode} node The AST node to get the comment for. |
| * @returns {Token|null} The Block comment token containing the JSDoc comment |
| * for the given node or null if not found. |
| * @public |
| * @deprecated |
| */ |
| getJSDocComment(node) { |
| |
| /** |
| * Checks for the presence of a JSDoc comment for the given node and returns it. |
| * @param {ASTNode} astNode The AST node to get the comment for. |
| * @returns {Token|null} The Block comment token containing the JSDoc comment |
| * for the given node or null if not found. |
| * @private |
| */ |
| const findJSDocComment = astNode => { |
| const tokenBefore = this.getTokenBefore(astNode, { includeComments: true }); |
| |
| if ( |
| tokenBefore && |
| isCommentToken(tokenBefore) && |
| tokenBefore.type === "Block" && |
| tokenBefore.value.charAt(0) === "*" && |
| astNode.loc.start.line - tokenBefore.loc.end.line <= 1 |
| ) { |
| return tokenBefore; |
| } |
| |
| return null; |
| }; |
| let parent = node.parent; |
| |
| switch (node.type) { |
| case "ClassDeclaration": |
| case "FunctionDeclaration": |
| return findJSDocComment(looksLikeExport(parent) ? parent : node); |
| |
| case "ClassExpression": |
| return findJSDocComment(parent.parent); |
| |
| case "ArrowFunctionExpression": |
| case "FunctionExpression": |
| if (parent.type !== "CallExpression" && parent.type !== "NewExpression") { |
| while ( |
| !this.getCommentsBefore(parent).length && |
| !/Function/u.test(parent.type) && |
| parent.type !== "MethodDefinition" && |
| parent.type !== "Property" |
| ) { |
| parent = parent.parent; |
| |
| if (!parent) { |
| break; |
| } |
| } |
| |
| if (parent && parent.type !== "FunctionDeclaration" && parent.type !== "Program") { |
| return findJSDocComment(parent); |
| } |
| } |
| |
| return findJSDocComment(node); |
| |
| // falls through |
| default: |
| return null; |
| } |
| } |
| |
| /** |
| * Gets the deepest node containing a range index. |
| * @param {int} index Range index of the desired node. |
| * @returns {ASTNode} The node if found or null if not found. |
| * @public |
| */ |
| getNodeByRangeIndex(index) { |
| let result = null; |
| |
| Traverser.traverse(this.ast, { |
| visitorKeys: this.visitorKeys, |
| enter(node) { |
| if (node.range[0] <= index && index < node.range[1]) { |
| result = node; |
| } else { |
| this.skip(); |
| } |
| }, |
| leave(node) { |
| if (node === result) { |
| this.break(); |
| } |
| } |
| }); |
| |
| return result; |
| } |
| |
| /** |
| * Determines if two tokens have at least one whitespace character |
| * between them. This completely disregards comments in making the |
| * determination, so comments count as zero-length substrings. |
| * @param {Token} first The token to check after. |
| * @param {Token} second The token to check before. |
| * @returns {boolean} True if there is only space between tokens, false |
| * if there is anything other than whitespace between tokens. |
| * @public |
| */ |
| isSpaceBetweenTokens(first, second) { |
| const text = this.text.slice(first.range[1], second.range[0]); |
| |
| return /\s/u.test(text.replace(/\/\*.*?\*\//gu, "")); |
| } |
| |
| /** |
| * Converts a source text index into a (line, column) pair. |
| * @param {number} index The index of a character in a file |
| * @returns {Object} A {line, column} location object with a 0-indexed column |
| * @public |
| */ |
| getLocFromIndex(index) { |
| if (typeof index !== "number") { |
| throw new TypeError("Expected `index` to be a number."); |
| } |
| |
| if (index < 0 || index > this.text.length) { |
| throw new RangeError(`Index out of range (requested index ${index}, but source text has length ${this.text.length}).`); |
| } |
| |
| /* |
| * For an argument of this.text.length, return the location one "spot" past the last character |
| * of the file. If the last character is a linebreak, the location will be column 0 of the next |
| * line; otherwise, the location will be in the next column on the same line. |
| * |
| * See getIndexFromLoc for the motivation for this special case. |
| */ |
| if (index === this.text.length) { |
| return { line: this.lines.length, column: this.lines[this.lines.length - 1].length }; |
| } |
| |
| /* |
| * To figure out which line rangeIndex is on, determine the last index at which rangeIndex could |
| * be inserted into lineIndices to keep the list sorted. |
| */ |
| const lineNumber = lodash.sortedLastIndex(this.lineStartIndices, index); |
| |
| return { line: lineNumber, column: index - this.lineStartIndices[lineNumber - 1] }; |
| } |
| |
| /** |
| * Converts a (line, column) pair into a range index. |
| * @param {Object} loc A line/column location |
| * @param {number} loc.line The line number of the location (1-indexed) |
| * @param {number} loc.column The column number of the location (0-indexed) |
| * @returns {number} The range index of the location in the file. |
| * @public |
| */ |
| getIndexFromLoc(loc) { |
| if (typeof loc !== "object" || typeof loc.line !== "number" || typeof loc.column !== "number") { |
| throw new TypeError("Expected `loc` to be an object with numeric `line` and `column` properties."); |
| } |
| |
| if (loc.line <= 0) { |
| throw new RangeError(`Line number out of range (line ${loc.line} requested). Line numbers should be 1-based.`); |
| } |
| |
| if (loc.line > this.lineStartIndices.length) { |
| throw new RangeError(`Line number out of range (line ${loc.line} requested, but only ${this.lineStartIndices.length} lines present).`); |
| } |
| |
| const lineStartIndex = this.lineStartIndices[loc.line - 1]; |
| const lineEndIndex = loc.line === this.lineStartIndices.length ? this.text.length : this.lineStartIndices[loc.line]; |
| const positionIndex = lineStartIndex + loc.column; |
| |
| /* |
| * By design, getIndexFromLoc({ line: lineNum, column: 0 }) should return the start index of |
| * the given line, provided that the line number is valid element of this.lines. Since the |
| * last element of this.lines is an empty string for files with trailing newlines, add a |
| * special case where getting the index for the first location after the end of the file |
| * will return the length of the file, rather than throwing an error. This allows rules to |
| * use getIndexFromLoc consistently without worrying about edge cases at the end of a file. |
| */ |
| if ( |
| loc.line === this.lineStartIndices.length && positionIndex > lineEndIndex || |
| loc.line < this.lineStartIndices.length && positionIndex >= lineEndIndex |
| ) { |
| throw new RangeError(`Column number out of range (column ${loc.column} requested, but the length of line ${loc.line} is ${lineEndIndex - lineStartIndex}).`); |
| } |
| |
| return positionIndex; |
| } |
| } |
| |
| module.exports = SourceCode; |