|
|
- /**
- * @fileoverview A module that filters reported problems based on `eslint-disable` and `eslint-enable` comments
- * @author Teddy Katz
- */
-
- "use strict";
-
- //------------------------------------------------------------------------------
- // Typedefs
- //------------------------------------------------------------------------------
-
- /** @typedef {import("../shared/types").LintMessage} LintMessage */
-
- //------------------------------------------------------------------------------
- // Module Definition
- //------------------------------------------------------------------------------
-
- const escapeRegExp = require("escape-string-regexp");
-
- /**
- * Compares the locations of two objects in a source file
- * @param {{line: number, column: number}} itemA The first object
- * @param {{line: number, column: number}} itemB The second object
- * @returns {number} A value less than 1 if itemA appears before itemB in the source file, greater than 1 if
- * itemA appears after itemB in the source file, or 0 if itemA and itemB have the same location.
- */
- function compareLocations(itemA, itemB) {
- return itemA.line - itemB.line || itemA.column - itemB.column;
- }
-
- /**
- * Groups a set of directives into sub-arrays by their parent comment.
- * @param {Iterable<Directive>} directives Unused directives to be removed.
- * @returns {Directive[][]} Directives grouped by their parent comment.
- */
- function groupByParentComment(directives) {
- const groups = new Map();
-
- for (const directive of directives) {
- const { unprocessedDirective: { parentComment } } = directive;
-
- if (groups.has(parentComment)) {
- groups.get(parentComment).push(directive);
- } else {
- groups.set(parentComment, [directive]);
- }
- }
-
- return [...groups.values()];
- }
-
- /**
- * Creates removal details for a set of directives within the same comment.
- * @param {Directive[]} directives Unused directives to be removed.
- * @param {Token} commentToken The backing Comment token.
- * @returns {{ description, fix, unprocessedDirective }[]} Details for later creation of output Problems.
- */
- function createIndividualDirectivesRemoval(directives, commentToken) {
-
- /*
- * `commentToken.value` starts right after `//` or `/*`.
- * All calculated offsets will be relative to this index.
- */
- const commentValueStart = commentToken.range[0] + "//".length;
-
- // Find where the list of rules starts. `\S+` matches with the directive name (e.g. `eslint-disable-line`)
- const listStartOffset = /^\s*\S+\s+/u.exec(commentToken.value)[0].length;
-
- /*
- * Get the list text without any surrounding whitespace. In order to preserve the original
- * formatting, we don't want to change that whitespace.
- *
- * // eslint-disable-line rule-one , rule-two , rule-three -- comment
- * ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
- */
- const listText = commentToken.value
- .slice(listStartOffset) // remove directive name and all whitespace before the list
- .split(/\s-{2,}\s/u)[0] // remove `-- comment`, if it exists
- .trimEnd(); // remove all whitespace after the list
-
- /*
- * We can assume that `listText` contains multiple elements.
- * Otherwise, this function wouldn't be called - if there is
- * only one rule in the list, then the whole comment must be removed.
- */
-
- return directives.map(directive => {
- const { ruleId } = directive;
-
- const regex = new RegExp(String.raw`(?:^|\s*,\s*)(?<quote>['"]?)${escapeRegExp(ruleId)}\k<quote>(?:\s*,\s*|$)`, "u");
- const match = regex.exec(listText);
- const matchedText = match[0];
- const matchStartOffset = listStartOffset + match.index;
- const matchEndOffset = matchStartOffset + matchedText.length;
-
- const firstIndexOfComma = matchedText.indexOf(",");
- const lastIndexOfComma = matchedText.lastIndexOf(",");
-
- let removalStartOffset, removalEndOffset;
-
- if (firstIndexOfComma !== lastIndexOfComma) {
-
- /*
- * Since there are two commas, this must one of the elements in the middle of the list.
- * Matched range starts where the previous rule name ends, and ends where the next rule name starts.
- *
- * // eslint-disable-line rule-one , rule-two , rule-three -- comment
- * ^^^^^^^^^^^^^^
- *
- * We want to remove only the content between the two commas, and also one of the commas.
- *
- * // eslint-disable-line rule-one , rule-two , rule-three -- comment
- * ^^^^^^^^^^^
- */
- removalStartOffset = matchStartOffset + firstIndexOfComma;
- removalEndOffset = matchStartOffset + lastIndexOfComma;
-
- } else {
-
- /*
- * This is either the first element or the last element.
- *
- * If this is the first element, matched range starts where the first rule name starts
- * and ends where the second rule name starts. This is exactly the range we want
- * to remove so that the second rule name will start where the first one was starting
- * and thus preserve the original formatting.
- *
- * // eslint-disable-line rule-one , rule-two , rule-three -- comment
- * ^^^^^^^^^^^
- *
- * Similarly, if this is the last element, we've already matched the range we want to
- * remove. The previous rule name will end where the last one was ending, relative
- * to the content on the right side.
- *
- * // eslint-disable-line rule-one , rule-two , rule-three -- comment
- * ^^^^^^^^^^^^^
- */
- removalStartOffset = matchStartOffset;
- removalEndOffset = matchEndOffset;
- }
-
- return {
- description: `'${ruleId}'`,
- fix: {
- range: [
- commentValueStart + removalStartOffset,
- commentValueStart + removalEndOffset
- ],
- text: ""
- },
- unprocessedDirective: directive.unprocessedDirective
- };
- });
- }
-
- /**
- * Creates a description of deleting an entire unused disable comment.
- * @param {Directive[]} directives Unused directives to be removed.
- * @param {Token} commentToken The backing Comment token.
- * @returns {{ description, fix, unprocessedDirective }} Details for later creation of an output Problem.
- */
- function createCommentRemoval(directives, commentToken) {
- const { range } = commentToken;
- const ruleIds = directives.filter(directive => directive.ruleId).map(directive => `'${directive.ruleId}'`);
-
- return {
- description: ruleIds.length <= 2
- ? ruleIds.join(" or ")
- : `${ruleIds.slice(0, ruleIds.length - 1).join(", ")}, or ${ruleIds[ruleIds.length - 1]}`,
- fix: {
- range,
- text: " "
- },
- unprocessedDirective: directives[0].unprocessedDirective
- };
- }
-
- /**
- * Parses details from directives to create output Problems.
- * @param {Iterable<Directive>} allDirectives Unused directives to be removed.
- * @returns {{ description, fix, unprocessedDirective }[]} Details for later creation of output Problems.
- */
- function processUnusedDirectives(allDirectives) {
- const directiveGroups = groupByParentComment(allDirectives);
-
- return directiveGroups.flatMap(
- directives => {
- const { parentComment } = directives[0].unprocessedDirective;
- const remainingRuleIds = new Set(parentComment.ruleIds);
-
- for (const directive of directives) {
- remainingRuleIds.delete(directive.ruleId);
- }
-
- return remainingRuleIds.size
- ? createIndividualDirectivesRemoval(directives, parentComment.commentToken)
- : [createCommentRemoval(directives, parentComment.commentToken)];
- }
- );
- }
-
- /**
- * Collect eslint-enable comments that are removing suppressions by eslint-disable comments.
- * @param {Directive[]} directives The directives to check.
- * @returns {Set<Directive>} The used eslint-enable comments
- */
- function collectUsedEnableDirectives(directives) {
-
- /**
- * A Map of `eslint-enable` keyed by ruleIds that may be marked as used.
- * If `eslint-enable` does not have a ruleId, the key will be `null`.
- * @type {Map<string|null, Directive>}
- */
- const enabledRules = new Map();
-
- /**
- * A Set of `eslint-enable` marked as used.
- * It is also the return value of `collectUsedEnableDirectives` function.
- * @type {Set<Directive>}
- */
- const usedEnableDirectives = new Set();
-
- /*
- * Checks the directives backwards to see if the encountered `eslint-enable` is used by the previous `eslint-disable`,
- * and if so, stores the `eslint-enable` in `usedEnableDirectives`.
- */
- for (let index = directives.length - 1; index >= 0; index--) {
- const directive = directives[index];
-
- if (directive.type === "disable") {
- if (enabledRules.size === 0) {
- continue;
- }
- if (directive.ruleId === null) {
-
- // If encounter `eslint-disable` without ruleId,
- // mark all `eslint-enable` currently held in enabledRules as used.
- // e.g.
- // /* eslint-disable */ <- current directive
- // /* eslint-enable rule-id1 */ <- used
- // /* eslint-enable rule-id2 */ <- used
- // /* eslint-enable */ <- used
- for (const enableDirective of enabledRules.values()) {
- usedEnableDirectives.add(enableDirective);
- }
- enabledRules.clear();
- } else {
- const enableDirective = enabledRules.get(directive.ruleId);
-
- if (enableDirective) {
-
- // If encounter `eslint-disable` with ruleId, and there is an `eslint-enable` with the same ruleId in enabledRules,
- // mark `eslint-enable` with ruleId as used.
- // e.g.
- // /* eslint-disable rule-id */ <- current directive
- // /* eslint-enable rule-id */ <- used
- usedEnableDirectives.add(enableDirective);
- } else {
- const enabledDirectiveWithoutRuleId = enabledRules.get(null);
-
- if (enabledDirectiveWithoutRuleId) {
-
- // If encounter `eslint-disable` with ruleId, and there is no `eslint-enable` with the same ruleId in enabledRules,
- // mark `eslint-enable` without ruleId as used.
- // e.g.
- // /* eslint-disable rule-id */ <- current directive
- // /* eslint-enable */ <- used
- usedEnableDirectives.add(enabledDirectiveWithoutRuleId);
- }
- }
- }
- } else if (directive.type === "enable") {
- if (directive.ruleId === null) {
-
- // If encounter `eslint-enable` without ruleId, the `eslint-enable` that follows it are unused.
- // So clear enabledRules.
- // e.g.
- // /* eslint-enable */ <- current directive
- // /* eslint-enable rule-id *// <- unused
- // /* eslint-enable */ <- unused
- enabledRules.clear();
- enabledRules.set(null, directive);
- } else {
- enabledRules.set(directive.ruleId, directive);
- }
- }
- }
- return usedEnableDirectives;
- }
-
- /**
- * This is the same as the exported function, except that it
- * doesn't handle disable-line and disable-next-line directives, and it always reports unused
- * disable directives.
- * @param {Object} options options for applying directives. This is the same as the options
- * for the exported function, except that `reportUnusedDisableDirectives` is not supported
- * (this function always reports unused disable directives).
- * @returns {{problems: LintMessage[], unusedDirectives: LintMessage[]}} An object with a list
- * of problems (including suppressed ones) and unused eslint-disable directives
- */
- function applyDirectives(options) {
- const problems = [];
- const usedDisableDirectives = new Set();
-
- for (const problem of options.problems) {
- let disableDirectivesForProblem = [];
- let nextDirectiveIndex = 0;
-
- while (
- nextDirectiveIndex < options.directives.length &&
- compareLocations(options.directives[nextDirectiveIndex], problem) <= 0
- ) {
- const directive = options.directives[nextDirectiveIndex++];
-
- if (directive.ruleId === null || directive.ruleId === problem.ruleId) {
- switch (directive.type) {
- case "disable":
- disableDirectivesForProblem.push(directive);
- break;
-
- case "enable":
- disableDirectivesForProblem = [];
- break;
-
- // no default
- }
- }
- }
-
- if (disableDirectivesForProblem.length > 0) {
- const suppressions = disableDirectivesForProblem.map(directive => ({
- kind: "directive",
- justification: directive.unprocessedDirective.justification
- }));
-
- if (problem.suppressions) {
- problem.suppressions = problem.suppressions.concat(suppressions);
- } else {
- problem.suppressions = suppressions;
- usedDisableDirectives.add(disableDirectivesForProblem[disableDirectivesForProblem.length - 1]);
- }
- }
-
- problems.push(problem);
- }
-
- const unusedDisableDirectivesToReport = options.directives
- .filter(directive => directive.type === "disable" && !usedDisableDirectives.has(directive));
-
-
- const unusedEnableDirectivesToReport = new Set(
- options.directives.filter(directive => directive.unprocessedDirective.type === "enable")
- );
-
- /*
- * If directives has the eslint-enable directive,
- * check whether the eslint-enable comment is used.
- */
- if (unusedEnableDirectivesToReport.size > 0) {
- for (const directive of collectUsedEnableDirectives(options.directives)) {
- unusedEnableDirectivesToReport.delete(directive);
- }
- }
-
- const processed = processUnusedDirectives(unusedDisableDirectivesToReport)
- .concat(processUnusedDirectives(unusedEnableDirectivesToReport));
-
- const unusedDirectives = processed
- .map(({ description, fix, unprocessedDirective }) => {
- const { parentComment, type, line, column } = unprocessedDirective;
-
- let message;
-
- if (type === "enable") {
- message = description
- ? `Unused eslint-enable directive (no matching eslint-disable directives were found for ${description}).`
- : "Unused eslint-enable directive (no matching eslint-disable directives were found).";
- } else {
- message = description
- ? `Unused eslint-disable directive (no problems were reported from ${description}).`
- : "Unused eslint-disable directive (no problems were reported).";
- }
- return {
- ruleId: null,
- message,
- line: type === "disable-next-line" ? parentComment.commentToken.loc.start.line : line,
- column: type === "disable-next-line" ? parentComment.commentToken.loc.start.column + 1 : column,
- severity: options.reportUnusedDisableDirectives === "warn" ? 1 : 2,
- nodeType: null,
- ...options.disableFixes ? {} : { fix }
- };
- });
-
- return { problems, unusedDirectives };
- }
-
- /**
- * Given a list of directive comments (i.e. metadata about eslint-disable and eslint-enable comments) and a list
- * of reported problems, adds the suppression information to the problems.
- * @param {Object} options Information about directives and problems
- * @param {{
- * type: ("disable"|"enable"|"disable-line"|"disable-next-line"),
- * ruleId: (string|null),
- * line: number,
- * column: number,
- * justification: string
- * }} options.directives Directive comments found in the file, with one-based columns.
- * Two directive comments can only have the same location if they also have the same type (e.g. a single eslint-disable
- * comment for two different rules is represented as two directives).
- * @param {{ruleId: (string|null), line: number, column: number}[]} options.problems
- * A list of problems reported by rules, sorted by increasing location in the file, with one-based columns.
- * @param {"off" | "warn" | "error"} options.reportUnusedDisableDirectives If `"warn"` or `"error"`, adds additional problems for unused directives
- * @param {boolean} options.disableFixes If true, it doesn't make `fix` properties.
- * @returns {{ruleId: (string|null), line: number, column: number, suppressions?: {kind: string, justification: string}}[]}
- * An object with a list of reported problems, the suppressed of which contain the suppression information.
- */
- module.exports = ({ directives, disableFixes, problems, reportUnusedDisableDirectives = "off" }) => {
- const blockDirectives = directives
- .filter(directive => directive.type === "disable" || directive.type === "enable")
- .map(directive => Object.assign({}, directive, { unprocessedDirective: directive }))
- .sort(compareLocations);
-
- const lineDirectives = directives.flatMap(directive => {
- switch (directive.type) {
- case "disable":
- case "enable":
- return [];
-
- case "disable-line":
- return [
- { type: "disable", line: directive.line, column: 1, ruleId: directive.ruleId, unprocessedDirective: directive },
- { type: "enable", line: directive.line + 1, column: 0, ruleId: directive.ruleId, unprocessedDirective: directive }
- ];
-
- case "disable-next-line":
- return [
- { type: "disable", line: directive.line + 1, column: 1, ruleId: directive.ruleId, unprocessedDirective: directive },
- { type: "enable", line: directive.line + 2, column: 0, ruleId: directive.ruleId, unprocessedDirective: directive }
- ];
-
- default:
- throw new TypeError(`Unrecognized directive type '${directive.type}'`);
- }
- }).sort(compareLocations);
-
- const blockDirectivesResult = applyDirectives({
- problems,
- directives: blockDirectives,
- disableFixes,
- reportUnusedDisableDirectives
- });
- const lineDirectivesResult = applyDirectives({
- problems: blockDirectivesResult.problems,
- directives: lineDirectives,
- disableFixes,
- reportUnusedDisableDirectives
- });
-
- return reportUnusedDisableDirectives !== "off"
- ? lineDirectivesResult.problems
- .concat(blockDirectivesResult.unusedDirectives)
- .concat(lineDirectivesResult.unusedDirectives)
- .sort(compareLocations)
- : lineDirectivesResult.problems;
- };
|