1267 lines
38 KiB
JavaScript
1267 lines
38 KiB
JavaScript
/**
|
|
* @fileoverview Abstraction of JavaScript source code.
|
|
* @author Nicholas C. Zakas
|
|
*/
|
|
'use strict';
|
|
|
|
//------------------------------------------------------------------------------
|
|
// Requirements
|
|
//------------------------------------------------------------------------------
|
|
|
|
const { isCommentToken } = require('@eslint-community/eslint-utils'),
|
|
TokenStore = require('./token-store'),
|
|
astUtils = require('../../../shared/ast-utils'),
|
|
Traverser = require('../../../shared/traverser'),
|
|
globals = require('../../../../conf/globals'),
|
|
{ directivesPattern } = require('../../../shared/directives'),
|
|
CodePathAnalyzer = require('../../../linter/code-path-analysis/code-path-analyzer'),
|
|
createEmitter = require('../../../linter/safe-emitter'),
|
|
{
|
|
ConfigCommentParser,
|
|
VisitNodeStep,
|
|
CallMethodStep,
|
|
Directive,
|
|
} = require('@eslint/plugin-kit'),
|
|
eslintScope = require('eslint-scope');
|
|
|
|
//------------------------------------------------------------------------------
|
|
// Type Definitions
|
|
//------------------------------------------------------------------------------
|
|
|
|
/** @typedef {import("eslint-scope").Variable} Variable */
|
|
/** @typedef {import("eslint-scope").Scope} Scope */
|
|
/** @typedef {import("@eslint/core").SourceCode} ISourceCode */
|
|
/** @typedef {import("@eslint/core").Directive} IDirective */
|
|
/** @typedef {import("@eslint/core").TraversalStep} ITraversalStep */
|
|
|
|
//------------------------------------------------------------------------------
|
|
// Private
|
|
//------------------------------------------------------------------------------
|
|
|
|
const commentParser = new ConfigCommentParser();
|
|
|
|
const CODE_PATH_EVENTS = [
|
|
'onCodePathStart',
|
|
'onCodePathEnd',
|
|
'onCodePathSegmentStart',
|
|
'onCodePathSegmentEnd',
|
|
'onCodePathSegmentLoop',
|
|
'onUnreachableCodePathSegmentStart',
|
|
'onUnreachableCodePathSegmentEnd',
|
|
];
|
|
|
|
/**
|
|
* 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) {
|
|
throw new TypeError(`Unexpected empty AST. (${ast})`);
|
|
}
|
|
|
|
if (!ast.tokens) {
|
|
throw new TypeError('AST is missing the tokens array.');
|
|
}
|
|
|
|
if (!ast.comments) {
|
|
throw new TypeError('AST is missing the comments array.');
|
|
}
|
|
|
|
if (!ast.loc) {
|
|
throw new TypeError('AST is missing location information.');
|
|
}
|
|
|
|
if (!ast.range) {
|
|
throw new TypeError('AST is missing range information');
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Retrieves globals for the given ecmaVersion.
|
|
* @param {number} ecmaVersion The version to retrieve globals for.
|
|
* @returns {Object} The globals for the given ecmaVersion.
|
|
*/
|
|
function getGlobalsForEcmaVersion(ecmaVersion) {
|
|
switch (ecmaVersion) {
|
|
case 3:
|
|
return globals.es3;
|
|
|
|
case 5:
|
|
return globals.es5;
|
|
|
|
default:
|
|
if (ecmaVersion < 2015) {
|
|
return globals[`es${ecmaVersion + 2009}`];
|
|
}
|
|
|
|
return globals[`es${ecmaVersion}`];
|
|
}
|
|
}
|
|
|
|
/**
|
|
* 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;
|
|
}
|
|
|
|
/**
|
|
* Normalizes a value for a global in a config
|
|
* @param {(boolean|string|null)} configuredValue The value given for a global in configuration or in
|
|
* a global directive comment
|
|
* @returns {("readable"|"writeable"|"off")} The value normalized as a string
|
|
* @throws Error if global value is invalid
|
|
*/
|
|
function normalizeConfigGlobal(configuredValue) {
|
|
switch (configuredValue) {
|
|
case 'off':
|
|
return 'off';
|
|
|
|
case true:
|
|
case 'true':
|
|
case 'writeable':
|
|
case 'writable':
|
|
return 'writable';
|
|
|
|
case null:
|
|
case false:
|
|
case 'false':
|
|
case 'readable':
|
|
case 'readonly':
|
|
return 'readonly';
|
|
|
|
default:
|
|
throw new Error(
|
|
`'${configuredValue}' is not a valid configuration for a global (use 'readonly', 'writable', or 'off')`
|
|
);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Determines if two nodes or tokens overlap.
|
|
* @param {ASTNode|Token} first The first node or token to check.
|
|
* @param {ASTNode|Token} second The second node or token to check.
|
|
* @returns {boolean} True if the two nodes or tokens overlap.
|
|
* @private
|
|
*/
|
|
function nodesOrTokensOverlap(first, second) {
|
|
return (
|
|
(first.range[0] <= second.range[0] && first.range[1] >= second.range[0]) ||
|
|
(second.range[0] <= first.range[0] && second.range[1] >= first.range[0])
|
|
);
|
|
}
|
|
|
|
/**
|
|
* Determines if two nodes or tokens have at least one whitespace character
|
|
* between them. Order does not matter. Returns false if the given nodes or
|
|
* tokens overlap.
|
|
* @param {SourceCode} sourceCode The source code object.
|
|
* @param {ASTNode|Token} first The first node or token to check between.
|
|
* @param {ASTNode|Token} second The second node or token to check between.
|
|
* @param {boolean} checkInsideOfJSXText If `true` is present, check inside of JSXText tokens for backward compatibility.
|
|
* @returns {boolean} True if there is a whitespace character between
|
|
* any of the tokens found between the two given nodes or tokens.
|
|
* @public
|
|
*/
|
|
function isSpaceBetween(sourceCode, first, second, checkInsideOfJSXText) {
|
|
if (nodesOrTokensOverlap(first, second)) {
|
|
return false;
|
|
}
|
|
|
|
const [startingNodeOrToken, endingNodeOrToken] =
|
|
first.range[1] <= second.range[0] ? [first, second] : [second, first];
|
|
const firstToken =
|
|
sourceCode.getLastToken(startingNodeOrToken) || startingNodeOrToken;
|
|
const finalToken =
|
|
sourceCode.getFirstToken(endingNodeOrToken) || endingNodeOrToken;
|
|
let currentToken = firstToken;
|
|
|
|
while (currentToken !== finalToken) {
|
|
const nextToken = sourceCode.getTokenAfter(currentToken, {
|
|
includeComments: true,
|
|
});
|
|
|
|
if (
|
|
currentToken.range[1] !== nextToken.range[0] ||
|
|
/*
|
|
* For backward compatibility, check spaces in JSXText.
|
|
* https://github.com/eslint/eslint/issues/12614
|
|
*/
|
|
(checkInsideOfJSXText &&
|
|
nextToken !== finalToken &&
|
|
nextToken.type === 'JSXText' &&
|
|
/\s/u.test(nextToken.value))
|
|
) {
|
|
return true;
|
|
}
|
|
|
|
currentToken = nextToken;
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
//-----------------------------------------------------------------------------
|
|
// Directive Comments
|
|
//-----------------------------------------------------------------------------
|
|
|
|
/**
|
|
* Ensures that variables representing built-in properties of the Global Object,
|
|
* and any globals declared by special block comments, are present in the global
|
|
* scope.
|
|
* @param {Scope} globalScope The global scope.
|
|
* @param {Object|undefined} configGlobals The globals declared in configuration
|
|
* @param {Object|undefined} inlineGlobals The globals declared in the source code
|
|
* @returns {void}
|
|
*/
|
|
function addDeclaredGlobals(
|
|
globalScope,
|
|
configGlobals = {},
|
|
inlineGlobals = {}
|
|
) {
|
|
// Define configured global variables.
|
|
for (const id of new Set([
|
|
...Object.keys(configGlobals),
|
|
...Object.keys(inlineGlobals),
|
|
])) {
|
|
/*
|
|
* `normalizeConfigGlobal` will throw an error if a configured global value is invalid. However, these errors would
|
|
* typically be caught when validating a config anyway (validity for inline global comments is checked separately).
|
|
*/
|
|
const configValue =
|
|
configGlobals[id] === void 0 ?
|
|
void 0
|
|
: normalizeConfigGlobal(configGlobals[id]);
|
|
const commentValue = inlineGlobals[id] && inlineGlobals[id].value;
|
|
const value = commentValue || configValue;
|
|
const sourceComments = inlineGlobals[id] && inlineGlobals[id].comments;
|
|
|
|
if (value === 'off') {
|
|
continue;
|
|
}
|
|
|
|
let variable = globalScope.set.get(id);
|
|
|
|
if (!variable) {
|
|
variable = new eslintScope.Variable(id, globalScope);
|
|
|
|
globalScope.variables.push(variable);
|
|
globalScope.set.set(id, variable);
|
|
}
|
|
|
|
variable.eslintImplicitGlobalSetting = configValue;
|
|
variable.eslintExplicitGlobal = sourceComments !== void 0;
|
|
variable.eslintExplicitGlobalComments = sourceComments;
|
|
variable.writeable = value === 'writable';
|
|
}
|
|
|
|
/*
|
|
* "through" contains all references which definitions cannot be found.
|
|
* Since we augment the global scope using configuration, we need to update
|
|
* references and remove the ones that were added by configuration.
|
|
*/
|
|
globalScope.through = globalScope.through.filter((reference) => {
|
|
const name = reference.identifier.name;
|
|
const variable = globalScope.set.get(name);
|
|
|
|
if (variable) {
|
|
/*
|
|
* Links the variable and the reference.
|
|
* And this reference is removed from `Scope#through`.
|
|
*/
|
|
reference.resolved = variable;
|
|
variable.references.push(reference);
|
|
|
|
return false;
|
|
}
|
|
|
|
return true;
|
|
});
|
|
}
|
|
|
|
/**
|
|
* Sets the given variable names as exported so they won't be triggered by
|
|
* the `no-unused-vars` rule.
|
|
* @param {eslint.Scope} globalScope The global scope to define exports in.
|
|
* @param {Record<string,string>} variables An object whose keys are the variable
|
|
* names to export.
|
|
* @returns {void}
|
|
*/
|
|
function markExportedVariables(globalScope, variables) {
|
|
Object.keys(variables).forEach((name) => {
|
|
const variable = globalScope.set.get(name);
|
|
|
|
if (variable) {
|
|
variable.eslintUsed = true;
|
|
variable.eslintExported = true;
|
|
}
|
|
});
|
|
}
|
|
|
|
//------------------------------------------------------------------------------
|
|
// Public Interface
|
|
//------------------------------------------------------------------------------
|
|
|
|
const caches = Symbol('caches');
|
|
|
|
/**
|
|
* Represents parsed source code.
|
|
* @implements {ISourceCode}
|
|
*/
|
|
class SourceCode extends TokenStore {
|
|
/**
|
|
* The cache of steps that were taken while traversing the source code.
|
|
* @type {Array<ITraversalStep>}
|
|
*/
|
|
#steps;
|
|
|
|
/**
|
|
* Creates a new instance.
|
|
* @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 {boolean} textOrConfig.hasBOM Indicates if the text has a Unicode BOM.
|
|
* @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(textOrConfig, astIfNoConfig) {
|
|
let text, hasBOM, ast, parserServices, scopeManager, visitorKeys;
|
|
|
|
// Process overloading of arguments
|
|
if (typeof textOrConfig === 'string') {
|
|
text = textOrConfig;
|
|
ast = astIfNoConfig;
|
|
hasBOM = false;
|
|
} else if (typeof textOrConfig === 'object' && textOrConfig !== null) {
|
|
text = textOrConfig.text;
|
|
ast = textOrConfig.ast;
|
|
hasBOM = textOrConfig.hasBOM;
|
|
parserServices = textOrConfig.parserServices;
|
|
scopeManager = textOrConfig.scopeManager;
|
|
visitorKeys = textOrConfig.visitorKeys;
|
|
}
|
|
|
|
validate(ast);
|
|
super(ast.tokens, ast.comments);
|
|
|
|
/**
|
|
* General purpose caching for the class.
|
|
*/
|
|
this[caches] = new Map([
|
|
['scopes', new WeakMap()],
|
|
['vars', new Map()],
|
|
['configNodes', void 0],
|
|
]);
|
|
|
|
/**
|
|
* Indicates if the AST is ESTree compatible.
|
|
* @type {boolean}
|
|
*/
|
|
this.isESTree = ast.type === 'Program';
|
|
|
|
/*
|
|
* Backwards compatibility for BOM handling.
|
|
*
|
|
* The `hasBOM` property has been available on the `SourceCode` object
|
|
* for a long time and is used to indicate if the source contains a BOM.
|
|
* The linter strips the BOM and just passes the `hasBOM` property to the
|
|
* `SourceCode` constructor to make it easier for languages to not deal with
|
|
* the BOM.
|
|
*
|
|
* However, the text passed in to the `SourceCode` constructor might still
|
|
* have a BOM if the constructor is called outside of the linter, so we still
|
|
* need to check for the BOM in the text.
|
|
*/
|
|
const textHasBOM = text.charCodeAt(0) === 0xfeff;
|
|
|
|
/**
|
|
* The flag to indicate that the source code has Unicode BOM.
|
|
* @type {boolean}
|
|
*/
|
|
this.hasBOM = textHasBOM || !!hasBOM;
|
|
|
|
/**
|
|
* The original text source code.
|
|
* BOM was stripped from this text.
|
|
* @type {string}
|
|
*/
|
|
this.text = textHasBOM ? 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.at(-1), match.index)
|
|
);
|
|
this.lineStartIndices.push(match.index + match[0].length);
|
|
}
|
|
this.lines.push(this.text.slice(this.lineStartIndices.at(-1)));
|
|
|
|
// don't allow further 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;
|
|
}
|
|
|
|
/**
|
|
* 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 nodes or tokens have at least one whitespace character
|
|
* between them. Order does not matter. Returns false if the given nodes or
|
|
* tokens overlap.
|
|
* @param {ASTNode|Token} first The first node or token to check between.
|
|
* @param {ASTNode|Token} second The second node or token to check between.
|
|
* @returns {boolean} True if there is a whitespace character between
|
|
* any of the tokens found between the two given nodes or tokens.
|
|
* @public
|
|
*/
|
|
isSpaceBetween(first, second) {
|
|
return isSpaceBetween(this, first, second, false);
|
|
}
|
|
|
|
/**
|
|
* Determines if two nodes or tokens have at least one whitespace character
|
|
* between them. Order does not matter. Returns false if the given nodes or
|
|
* tokens overlap.
|
|
* For backward compatibility, this method returns true if there are
|
|
* `JSXText` tokens that contain whitespaces between the two.
|
|
* @param {ASTNode|Token} first The first node or token to check between.
|
|
* @param {ASTNode|Token} second The second node or token to check between.
|
|
* @returns {boolean} True if there is a whitespace character between
|
|
* any of the tokens found between the two given nodes or tokens.
|
|
* @deprecated in favor of isSpaceBetween().
|
|
* @public
|
|
*/
|
|
isSpaceBetweenTokens(first, second) {
|
|
return isSpaceBetween(this, first, second, true);
|
|
}
|
|
|
|
/**
|
|
* Converts a source text index into a (line, column) pair.
|
|
* @param {number} index The index of a character in a file
|
|
* @throws {TypeError} If non-numeric index or index out of range.
|
|
* @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.at(-1).length,
|
|
};
|
|
}
|
|
|
|
/*
|
|
* To figure out which line index is on, determine the last place at which index could
|
|
* be inserted into lineStartIndices to keep the list sorted.
|
|
*/
|
|
const lineNumber =
|
|
index >= this.lineStartIndices.at(-1) ?
|
|
this.lineStartIndices.length
|
|
: this.lineStartIndices.findIndex((el) => index < el);
|
|
|
|
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)
|
|
* @throws {TypeError|RangeError} If `loc` is not an object with a numeric
|
|
* `line` and `column`, if the `line` is less than or equal to zero or
|
|
* the line or column is out of the expected range.
|
|
* @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;
|
|
}
|
|
|
|
/**
|
|
* Gets the scope for the given node
|
|
* @param {ASTNode} currentNode The node to get the scope of
|
|
* @returns {Scope} The scope information for this node
|
|
* @throws {TypeError} If the `currentNode` argument is missing.
|
|
*/
|
|
getScope(currentNode) {
|
|
if (!currentNode) {
|
|
throw new TypeError('Missing required argument: node.');
|
|
}
|
|
|
|
// check cache first
|
|
const cache = this[caches].get('scopes');
|
|
const cachedScope = cache.get(currentNode);
|
|
|
|
if (cachedScope) {
|
|
return cachedScope;
|
|
}
|
|
|
|
// On Program node, get the outermost scope to avoid return Node.js special function scope or ES modules scope.
|
|
const inner = currentNode.type !== 'Program';
|
|
|
|
for (let node = currentNode; node; node = node.parent) {
|
|
const scope = this.scopeManager.acquire(node, inner);
|
|
|
|
if (scope) {
|
|
if (scope.type === 'function-expression-name') {
|
|
cache.set(currentNode, scope.childScopes[0]);
|
|
return scope.childScopes[0];
|
|
}
|
|
|
|
cache.set(currentNode, scope);
|
|
return scope;
|
|
}
|
|
}
|
|
|
|
cache.set(currentNode, this.scopeManager.scopes[0]);
|
|
return this.scopeManager.scopes[0];
|
|
}
|
|
|
|
/**
|
|
* Get the variables that `node` defines.
|
|
* This is a convenience method that passes through
|
|
* to the same method on the `scopeManager`.
|
|
* @param {ASTNode} node The node for which the variables are obtained.
|
|
* @returns {Array<Variable>} An array of variable nodes representing
|
|
* the variables that `node` defines.
|
|
*/
|
|
getDeclaredVariables(node) {
|
|
return this.scopeManager.getDeclaredVariables(node);
|
|
}
|
|
|
|
/* eslint-disable class-methods-use-this -- node is owned by SourceCode */
|
|
/**
|
|
* Gets all the ancestors of a given node
|
|
* @param {ASTNode} node The node
|
|
* @returns {Array<ASTNode>} All the ancestor nodes in the AST, not including the provided node, starting
|
|
* from the root node at index 0 and going inwards to the parent node.
|
|
* @throws {TypeError} When `node` is missing.
|
|
*/
|
|
getAncestors(node) {
|
|
if (!node) {
|
|
throw new TypeError('Missing required argument: node.');
|
|
}
|
|
|
|
const ancestorsStartingAtParent = [];
|
|
|
|
for (let ancestor = node.parent; ancestor; ancestor = ancestor.parent) {
|
|
ancestorsStartingAtParent.push(ancestor);
|
|
}
|
|
|
|
return ancestorsStartingAtParent.reverse();
|
|
}
|
|
|
|
/**
|
|
* Returns the location of the given node or token.
|
|
* @param {ASTNode|Token} nodeOrToken The node or token to get the location of.
|
|
* @returns {SourceLocation} The location of the node or token.
|
|
*/
|
|
getLoc(nodeOrToken) {
|
|
return nodeOrToken.loc;
|
|
}
|
|
|
|
/**
|
|
* Returns the range of the given node or token.
|
|
* @param {ASTNode|Token} nodeOrToken The node or token to get the range of.
|
|
* @returns {[number, number]} The range of the node or token.
|
|
*/
|
|
getRange(nodeOrToken) {
|
|
return nodeOrToken.range;
|
|
}
|
|
|
|
/* eslint-enable class-methods-use-this -- node is owned by SourceCode */
|
|
|
|
/**
|
|
* Marks a variable as used in the current scope
|
|
* @param {string} name The name of the variable to mark as used.
|
|
* @param {ASTNode} [refNode] The closest node to the variable reference.
|
|
* @returns {boolean} True if the variable was found and marked as used, false if not.
|
|
*/
|
|
markVariableAsUsed(name, refNode = this.ast) {
|
|
const currentScope = this.getScope(refNode);
|
|
let initialScope = currentScope;
|
|
|
|
/*
|
|
* When we are in an ESM or CommonJS module, we need to start searching
|
|
* from the top-level scope, not the global scope. For ESM the top-level
|
|
* scope is the module scope; for CommonJS the top-level scope is the
|
|
* outer function scope.
|
|
*
|
|
* Without this check, we might miss a variable declared with `var` at
|
|
* the top-level because it won't exist in the global scope.
|
|
*/
|
|
if (
|
|
currentScope.type === 'global' &&
|
|
currentScope.childScopes.length > 0 &&
|
|
// top-level scopes refer to a `Program` node
|
|
currentScope.childScopes[0].block === this.ast
|
|
) {
|
|
initialScope = currentScope.childScopes[0];
|
|
}
|
|
|
|
for (let scope = initialScope; scope; scope = scope.upper) {
|
|
const variable = scope.variables.find(
|
|
(scopeVar) => scopeVar.name === name
|
|
);
|
|
|
|
if (variable) {
|
|
variable.eslintUsed = true;
|
|
return true;
|
|
}
|
|
}
|
|
|
|
return false;
|
|
}
|
|
|
|
/**
|
|
* Returns an array of all inline configuration nodes found in the
|
|
* source code.
|
|
* @returns {Array<Token>} An array of all inline configuration nodes.
|
|
*/
|
|
getInlineConfigNodes() {
|
|
// check the cache first
|
|
let configNodes = this[caches].get('configNodes');
|
|
|
|
if (configNodes) {
|
|
return configNodes;
|
|
}
|
|
|
|
// calculate fresh config nodes
|
|
configNodes = this.ast.comments.filter((comment) => {
|
|
// shebang comments are never directives
|
|
if (comment.type === 'Shebang') {
|
|
return false;
|
|
}
|
|
|
|
const directive = commentParser.parseDirective(comment.value);
|
|
|
|
if (!directive) {
|
|
return false;
|
|
}
|
|
|
|
if (!directivesPattern.test(directive.label)) {
|
|
return false;
|
|
}
|
|
|
|
// only certain comment types are supported as line comments
|
|
return (
|
|
comment.type !== 'Line' ||
|
|
!!/^eslint-disable-(next-)?line$/u.test(directive.label)
|
|
);
|
|
});
|
|
|
|
this[caches].set('configNodes', configNodes);
|
|
|
|
return configNodes;
|
|
}
|
|
|
|
/**
|
|
* Returns an all directive nodes that enable or disable rules along with any problems
|
|
* encountered while parsing the directives.
|
|
* @returns {{problems:Array<Problem>,directives:Array<Directive>}} Information
|
|
* that ESLint needs to further process the directives.
|
|
*/
|
|
getDisableDirectives() {
|
|
// check the cache first
|
|
const cachedDirectives = this[caches].get('disableDirectives');
|
|
|
|
if (cachedDirectives) {
|
|
return cachedDirectives;
|
|
}
|
|
|
|
const problems = [];
|
|
const directives = [];
|
|
|
|
this.getInlineConfigNodes().forEach((comment) => {
|
|
// Step 1: Parse the directive
|
|
const {
|
|
label,
|
|
value,
|
|
justification: justificationPart,
|
|
} = commentParser.parseDirective(comment.value);
|
|
|
|
// Step 2: Extract the directive value
|
|
const lineCommentSupported = /^eslint-disable-(next-)?line$/u.test(label);
|
|
|
|
if (comment.type === 'Line' && !lineCommentSupported) {
|
|
return;
|
|
}
|
|
|
|
// Step 3: Validate the directive does not span multiple lines
|
|
if (
|
|
label === 'eslint-disable-line' &&
|
|
comment.loc.start.line !== comment.loc.end.line
|
|
) {
|
|
const message = `${label} comment should not span multiple lines.`;
|
|
|
|
problems.push({
|
|
ruleId: null,
|
|
message,
|
|
loc: comment.loc,
|
|
});
|
|
return;
|
|
}
|
|
|
|
// Step 4: Extract the directive value and create the Directive object
|
|
switch (label) {
|
|
case 'eslint-disable':
|
|
case 'eslint-enable':
|
|
case 'eslint-disable-next-line':
|
|
case 'eslint-disable-line': {
|
|
const directiveType = label.slice('eslint-'.length);
|
|
|
|
directives.push(
|
|
new Directive({
|
|
type: directiveType,
|
|
node: comment,
|
|
value,
|
|
justification: justificationPart,
|
|
})
|
|
);
|
|
}
|
|
|
|
// no default
|
|
}
|
|
});
|
|
|
|
const result = { problems, directives };
|
|
|
|
this[caches].set('disableDirectives', result);
|
|
|
|
return result;
|
|
}
|
|
|
|
/**
|
|
* Applies language options sent in from the core.
|
|
* @param {Object} languageOptions The language options for this run.
|
|
* @returns {void}
|
|
*/
|
|
applyLanguageOptions(languageOptions) {
|
|
/*
|
|
* Add configured globals and language globals
|
|
*
|
|
* Using Object.assign instead of object spread for performance reasons
|
|
* https://github.com/eslint/eslint/issues/16302
|
|
*/
|
|
const configGlobals = Object.assign(
|
|
Object.create(null), // https://github.com/eslint/eslint/issues/18363
|
|
getGlobalsForEcmaVersion(languageOptions.ecmaVersion),
|
|
languageOptions.sourceType === 'commonjs' ? globals.commonjs : void 0,
|
|
languageOptions.globals
|
|
);
|
|
const varsCache = this[caches].get('vars');
|
|
|
|
varsCache.set('configGlobals', configGlobals);
|
|
}
|
|
|
|
/**
|
|
* Applies configuration found inside of the source code. This method is only
|
|
* called when ESLint is running with inline configuration allowed.
|
|
* @returns {{problems:Array<Problem>,configs:{config:FlatConfigArray,loc:Location}}} Information
|
|
* that ESLint needs to further process the inline configuration.
|
|
*/
|
|
applyInlineConfig() {
|
|
const problems = [];
|
|
const configs = [];
|
|
const exportedVariables = {};
|
|
const inlineGlobals = Object.create(null);
|
|
|
|
this.getInlineConfigNodes().forEach((comment) => {
|
|
const { label, value } = commentParser.parseDirective(comment.value);
|
|
|
|
switch (label) {
|
|
case 'exported':
|
|
Object.assign(
|
|
exportedVariables,
|
|
commentParser.parseListConfig(value)
|
|
);
|
|
break;
|
|
|
|
case 'globals':
|
|
case 'global':
|
|
for (const [id, idSetting] of Object.entries(
|
|
commentParser.parseStringConfig(value)
|
|
)) {
|
|
let normalizedValue;
|
|
|
|
try {
|
|
normalizedValue = normalizeConfigGlobal(idSetting);
|
|
} catch (err) {
|
|
problems.push({
|
|
ruleId: null,
|
|
loc: comment.loc,
|
|
message: err.message,
|
|
});
|
|
continue;
|
|
}
|
|
|
|
if (inlineGlobals[id]) {
|
|
inlineGlobals[id].comments.push(comment);
|
|
inlineGlobals[id].value = normalizedValue;
|
|
} else {
|
|
inlineGlobals[id] = {
|
|
comments: [comment],
|
|
value: normalizedValue,
|
|
};
|
|
}
|
|
}
|
|
break;
|
|
|
|
case 'eslint': {
|
|
const parseResult = commentParser.parseJSONLikeConfig(value);
|
|
|
|
if (parseResult.ok) {
|
|
configs.push({
|
|
config: {
|
|
rules: parseResult.config,
|
|
},
|
|
loc: comment.loc,
|
|
});
|
|
} else {
|
|
problems.push({
|
|
ruleId: null,
|
|
loc: comment.loc,
|
|
message: parseResult.error.message,
|
|
});
|
|
}
|
|
|
|
break;
|
|
}
|
|
|
|
// no default
|
|
}
|
|
});
|
|
|
|
// save all the new variables for later
|
|
const varsCache = this[caches].get('vars');
|
|
|
|
varsCache.set('inlineGlobals', inlineGlobals);
|
|
varsCache.set('exportedVariables', exportedVariables);
|
|
|
|
return {
|
|
configs,
|
|
problems,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Called by ESLint core to indicate that it has finished providing
|
|
* information. We now add in all the missing variables and ensure that
|
|
* state-changing methods cannot be called by rules.
|
|
* @returns {void}
|
|
*/
|
|
finalize() {
|
|
const varsCache = this[caches].get('vars');
|
|
const configGlobals = varsCache.get('configGlobals');
|
|
const inlineGlobals = varsCache.get('inlineGlobals');
|
|
const exportedVariables = varsCache.get('exportedVariables');
|
|
const globalScope = this.scopeManager.scopes[0];
|
|
|
|
addDeclaredGlobals(globalScope, configGlobals, inlineGlobals);
|
|
|
|
if (exportedVariables) {
|
|
markExportedVariables(globalScope, exportedVariables);
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Traverse the source code and return the steps that were taken.
|
|
* @returns {Array<TraversalStep>} The steps that were taken while traversing the source code.
|
|
*/
|
|
traverse() {
|
|
// Because the AST doesn't mutate, we can cache the steps
|
|
if (this.#steps) {
|
|
return this.#steps;
|
|
}
|
|
|
|
const steps = (this.#steps = []);
|
|
|
|
/*
|
|
* This logic works for any AST, not just ESTree. Because ESLint has allowed
|
|
* custom parsers to return any AST, we need to ensure that the traversal
|
|
* logic works for any AST.
|
|
*/
|
|
const emitter = createEmitter();
|
|
let analyzer = {
|
|
enterNode(node) {
|
|
steps.push(
|
|
new VisitNodeStep({
|
|
target: node,
|
|
phase: 1,
|
|
args: [node, node.parent],
|
|
})
|
|
);
|
|
},
|
|
leaveNode(node) {
|
|
steps.push(
|
|
new VisitNodeStep({
|
|
target: node,
|
|
phase: 2,
|
|
args: [node, node.parent],
|
|
})
|
|
);
|
|
},
|
|
emitter,
|
|
};
|
|
|
|
/*
|
|
* We do code path analysis for ESTree only. Code path analysis is not
|
|
* necessary for other ASTs, and it's also not possible to do for other
|
|
* ASTs because the necessary information is not available.
|
|
*
|
|
* Generally speaking, we can tell that the AST is an ESTree if it has a
|
|
* Program node at the top level. This is not a perfect heuristic, but it
|
|
* is good enough for now.
|
|
*/
|
|
if (this.isESTree) {
|
|
analyzer = new CodePathAnalyzer(analyzer);
|
|
|
|
CODE_PATH_EVENTS.forEach((eventName) => {
|
|
emitter.on(eventName, (...args) => {
|
|
steps.push(
|
|
new CallMethodStep({
|
|
target: eventName,
|
|
args,
|
|
})
|
|
);
|
|
});
|
|
});
|
|
}
|
|
|
|
/*
|
|
* The actual AST traversal is done by the `Traverser` class. This class
|
|
* is responsible for walking the AST and calling the appropriate methods
|
|
* on the `analyzer` object, which is appropriate for the given AST.
|
|
*/
|
|
Traverser.traverse(this.ast, {
|
|
enter(node, parent) {
|
|
// save the parent node on a property for backwards compatibility
|
|
node.parent = parent;
|
|
|
|
analyzer.enterNode(node);
|
|
},
|
|
leave(node) {
|
|
analyzer.leaveNode(node);
|
|
},
|
|
visitorKeys: this.visitorKeys,
|
|
});
|
|
|
|
return steps;
|
|
}
|
|
}
|
|
|
|
module.exports = SourceCode;
|