mirror of https://github.com/lukechilds/node.git
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
416 lines
14 KiB
416 lines
14 KiB
/**
|
|
* @fileoverview Abstraction of JavaScript source code.
|
|
* @author Nicholas C. Zakas
|
|
*/
|
|
"use strict";
|
|
|
|
//------------------------------------------------------------------------------
|
|
// Requirements
|
|
//------------------------------------------------------------------------------
|
|
|
|
const TokenStore = require("../token-store"),
|
|
Traverser = require("./traverser"),
|
|
astUtils = require("../ast-utils"),
|
|
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");
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Finds a JSDoc comment node in an array of comment nodes.
|
|
* @param {ASTNode[]} comments The array of comment nodes to search.
|
|
* @param {int} line Line number to look around
|
|
* @returns {ASTNode} The node if found, null if not.
|
|
* @private
|
|
*/
|
|
function findJSDocComment(comments, line) {
|
|
|
|
if (comments) {
|
|
for (let i = comments.length - 1; i >= 0; i--) {
|
|
if (comments[i].type === "Block" && comments[i].value.charAt(0) === "*") {
|
|
|
|
if (line - comments[i].loc.end.line <= 1) {
|
|
return comments[i];
|
|
}
|
|
break;
|
|
|
|
}
|
|
}
|
|
}
|
|
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Check to see if its a ES6 export declaration
|
|
* @param {ASTNode} astNode - any node
|
|
* @returns {boolean} whether the given node represents a 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
|
|
*/
|
|
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
|
|
//------------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Represents parsed source code.
|
|
* @param {string} text - The source code text.
|
|
* @param {ASTNode} ast - The Program node of the AST representing the code. This AST should be created from the text that BOM was stripped.
|
|
* @constructor
|
|
*/
|
|
function SourceCode(text, ast) {
|
|
validate(ast);
|
|
|
|
/**
|
|
* 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 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]));
|
|
|
|
this.tokensAndComments = sortedMerge(ast.tokens, ast.comments);
|
|
|
|
// create token store methods
|
|
const tokenStore = new TokenStore(ast.tokens, ast.comments);
|
|
|
|
for (const methodName of TokenStore.PUBLIC_METHODS) {
|
|
this[methodName] = tokenStore[methodName].bind(tokenStore);
|
|
}
|
|
|
|
// 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
|
|
*/
|
|
SourceCode.splitLines = function(text) {
|
|
return text.split(astUtils.createGlobalLinebreakMatcher());
|
|
};
|
|
|
|
SourceCode.prototype = {
|
|
constructor: SourceCode,
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
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.
|
|
*/
|
|
getLines() {
|
|
return this.lines;
|
|
},
|
|
|
|
/**
|
|
* Retrieves an array containing all comments in the source code.
|
|
* @returns {ASTNode[]} An array of comment nodes.
|
|
*/
|
|
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} The list of comments indexed by their position.
|
|
* @public
|
|
*/
|
|
getComments(node) {
|
|
|
|
let leadingComments = node.leadingComments || [];
|
|
const trailingComments = node.trailingComments || [];
|
|
|
|
/*
|
|
* espree adds a "comments" array on Program nodes rather than
|
|
* leadingComments/trailingComments. Comments are only left in the
|
|
* Program node comments array if there is no executable code.
|
|
*/
|
|
if (node.type === "Program") {
|
|
if (node.body.length === 0) {
|
|
leadingComments = node.comments;
|
|
}
|
|
}
|
|
|
|
return {
|
|
leading: leadingComments,
|
|
trailing: trailingComments
|
|
};
|
|
},
|
|
|
|
/**
|
|
* Retrieves the JSDoc comment for a given node.
|
|
* @param {ASTNode} node The AST node to get the comment for.
|
|
* @returns {ASTNode} The BlockComment node containing the JSDoc for the
|
|
* given node or null if not found.
|
|
* @public
|
|
*/
|
|
getJSDocComment(node) {
|
|
|
|
let parent = node.parent;
|
|
|
|
switch (node.type) {
|
|
case "ClassDeclaration":
|
|
case "FunctionDeclaration":
|
|
if (looksLikeExport(parent)) {
|
|
return findJSDocComment(parent.leadingComments, parent.loc.start.line);
|
|
}
|
|
return findJSDocComment(node.leadingComments, node.loc.start.line);
|
|
|
|
case "ClassExpression":
|
|
return findJSDocComment(parent.parent.leadingComments, parent.parent.loc.start.line);
|
|
|
|
case "ArrowFunctionExpression":
|
|
case "FunctionExpression":
|
|
|
|
if (parent.type !== "CallExpression" && parent.type !== "NewExpression") {
|
|
while (parent && !parent.leadingComments && !/Function/.test(parent.type) && parent.type !== "MethodDefinition" && parent.type !== "Property") {
|
|
parent = parent.parent;
|
|
}
|
|
|
|
return parent && (parent.type !== "FunctionDeclaration") ? findJSDocComment(parent.leadingComments, parent.loc.start.line) : null;
|
|
} else if (node.leadingComments) {
|
|
return findJSDocComment(node.leadingComments, node.loc.start.line);
|
|
}
|
|
|
|
// 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.
|
|
*/
|
|
getNodeByRangeIndex(index) {
|
|
let result = null,
|
|
resultParent = null;
|
|
const traverser = new Traverser();
|
|
|
|
traverser.traverse(this.ast, {
|
|
enter(node, parent) {
|
|
if (node.range[0] <= index && index < node.range[1]) {
|
|
result = node;
|
|
resultParent = parent;
|
|
} else {
|
|
this.skip();
|
|
}
|
|
},
|
|
leave(node) {
|
|
if (node === result) {
|
|
this.break();
|
|
}
|
|
}
|
|
});
|
|
|
|
return result ? Object.assign({ parent: resultParent }, result) : null;
|
|
},
|
|
|
|
/**
|
|
* 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.
|
|
*/
|
|
isSpaceBetweenTokens(first, second) {
|
|
const text = this.text.slice(first.range[1], second.range[0]);
|
|
|
|
return /\s/.test(text.replace(/\/\*.*?\*\//g, ""));
|
|
},
|
|
|
|
/**
|
|
* 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
|
|
*/
|
|
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.
|
|
*/
|
|
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;
|
|
|