eslint/lib/cli.js

   1 /**
   2  * @fileoverview Main CLI object.
   3  * @author Nicholas C. Zakas
   4  */
   5
   6 "use strict";
   7
   8 /*
   9  * NOTE: The CLI object should *not* call process.exit() directly. It should only return
  10  * exit codes. This allows other programs to use the CLI object and still control
  11  * when the program exits.
  12  */
  13
  14 //------------------------------------------------------------------------------
  15 // Requirements
  16 //------------------------------------------------------------------------------
  17
  18 const fs = require("fs"),
  19     path = require("path"),
  20     { promisify } = require("util"),
  21     { ESLint } = require("./eslint"),
  22     { FlatESLint, shouldUseFlatConfig } = require("./eslint/flat-eslint"),
  23     createCLIOptions = require("./options"),
  24     log = require("./shared/logging"),
  25     RuntimeInfo = require("./shared/runtime-info");
  26 const { Legacy: { naming } } = require("@eslint/eslintrc");
  27 const { ModuleImporter } = require("@humanwhocodes/module-importer");
  28
  29 const debug = require("debug")("eslint:cli");
  30
  31 //------------------------------------------------------------------------------
  32 // Types
  33 //------------------------------------------------------------------------------
  34
  35 /** @typedef {import("./eslint/eslint").ESLintOptions} ESLintOptions */
  36 /** @typedef {import("./eslint/eslint").LintMessage} LintMessage */
  37 /** @typedef {import("./eslint/eslint").LintResult} LintResult */
  38 /** @typedef {import("./options").ParsedCLIOptions} ParsedCLIOptions */
  39 /** @typedef {import("./shared/types").ResultsMeta} ResultsMeta */
  40
  41 //------------------------------------------------------------------------------
  42 // Helpers
  43 //------------------------------------------------------------------------------
  44
  45 const mkdir = promisify(fs.mkdir);
  46 const stat = promisify(fs.stat);
  47 const writeFile = promisify(fs.writeFile);
  48
  49 /**
  50  * Predicate function for whether or not to apply fixes in quiet mode.
  51  * If a message is a warning, do not apply a fix.
  52  * @param {LintMessage} message The lint result.
  53  * @returns {boolean} True if the lint message is an error (and thus should be
  54  * autofixed), false otherwise.
  55  */
  56 function quietFixPredicate(message) {
  57     return message.severity === 2;
  58 }
  59
  60 /**
  61  * Translates the CLI options into the options expected by the ESLint constructor.
  62  * @param {ParsedCLIOptions} cliOptions The CLI options to translate.
  63  * @param {"flat"|"eslintrc"} [configType="eslintrc"] The format of the
  64  *      config to generate.
  65  * @returns {Promise<ESLintOptions>} The options object for the ESLint constructor.
  66  * @private
  67  */
  68 async function translateOptions({
  69     cache,
  70     cacheFile,
  71     cacheLocation,
  72     cacheStrategy,
  73     config,
  74     configLookup,
  75     env,
  76     errorOnUnmatchedPattern,
  77     eslintrc,
  78     ext,
  79     fix,
  80     fixDryRun,
  81     fixType,
  82     global,
  83     ignore,
  84     ignorePath,
  85     ignorePattern,
  86     inlineConfig,
  87     parser,
  88     parserOptions,
  89     plugin,
  90     quiet,
  91     reportUnusedDisableDirectives,
  92     resolvePluginsRelativeTo,
  93     rule,
  94     rulesdir
  95 }, configType) {
  96
  97     let overrideConfig, overrideConfigFile;
  98     const importer = new ModuleImporter();
  99
 100     if (configType === "flat") {
 101         overrideConfigFile = (typeof config === "string") ? config : !configLookup;
 102         if (overrideConfigFile === false) {
 103             overrideConfigFile = void 0;
 104         }
 105
 106         let globals = {};
 107
 108         if (global) {
 109             globals = global.reduce((obj, name) => {
 110                 if (name.endsWith(":true")) {
 111                     obj[name.slice(0, -5)] = "writable";
 112                 } else {
 113                     obj[name] = "readonly";
 114                 }
 115                 return obj;
 116             }, globals);
 117         }
 118
 119         overrideConfig = [{
 120             languageOptions: {
 121                 globals,
 122                 parserOptions: parserOptions || {}
 123             },
 124             rules: rule ? rule : {}
 125         }];
 126
 127         if (parser) {
 128             overrideConfig[0].languageOptions.parser = await importer.import(parser);
 129         }
 130
 131         if (plugin) {
 132             const plugins = {};
 133
 134             for (const pluginName of plugin) {
 135
 136                 const shortName = naming.getShorthandName(pluginName, "eslint-plugin");
 137                 const longName = naming.normalizePackageName(pluginName, "eslint-plugin");
 138
 139                 plugins[shortName] = await importer.import(longName);
 140             }
 141
 142             overrideConfig[0].plugins = plugins;
 143         }
 144
 145     } else {
 146         overrideConfigFile = config;
 147
 148         overrideConfig = {
 149             env: env && env.reduce((obj, name) => {
 150                 obj[name] = true;
 151                 return obj;
 152             }, {}),
 153             globals: global && global.reduce((obj, name) => {
 154                 if (name.endsWith(":true")) {
 155                     obj[name.slice(0, -5)] = "writable";
 156                 } else {
 157                     obj[name] = "readonly";
 158                 }
 159                 return obj;
 160             }, {}),
 161             ignorePatterns: ignorePattern,
 162             parser,
 163             parserOptions,
 164             plugins: plugin,
 165             rules: rule
 166         };
 167     }
 168
 169     const options = {
 170         allowInlineConfig: inlineConfig,
 171         cache,
 172         cacheLocation: cacheLocation || cacheFile,
 173         cacheStrategy,
 174         errorOnUnmatchedPattern,
 175         fix: (fix || fixDryRun) && (quiet ? quietFixPredicate : true),
 176         fixTypes: fixType,
 177         ignore,
 178         overrideConfig,
 179         overrideConfigFile,
 180         reportUnusedDisableDirectives: reportUnusedDisableDirectives ? "error" : void 0
 181     };
 182
 183     if (configType === "flat") {
 184         options.ignorePatterns = ignorePattern;
 185     } else {
 186         options.resolvePluginsRelativeTo = resolvePluginsRelativeTo;
 187         options.rulePaths = rulesdir;
 188         options.useEslintrc = eslintrc;
 189         options.extensions = ext;
 190         options.ignorePath = ignorePath;
 191     }
 192
 193     return options;
 194 }
 195
 196 /**
 197  * Count error messages.
 198  * @param {LintResult[]} results The lint results.
 199  * @returns {{errorCount:number;fatalErrorCount:number,warningCount:number}} The number of error messages.
 200  */
 201 function countErrors(results) {
 202     let errorCount = 0;
 203     let fatalErrorCount = 0;
 204     let warningCount = 0;
 205
 206     for (const result of results) {
 207         errorCount += result.errorCount;
 208         fatalErrorCount += result.fatalErrorCount;
 209         warningCount += result.warningCount;
 210     }
 211
 212     return { errorCount, fatalErrorCount, warningCount };
 213 }
 214
 215 /**
 216  * Check if a given file path is a directory or not.
 217  * @param {string} filePath The path to a file to check.
 218  * @returns {Promise<boolean>} `true` if the given path is a directory.
 219  */
 220 async function isDirectory(filePath) {
 221     try {
 222         return (await stat(filePath)).isDirectory();
 223     } catch (error) {
 224         if (error.code === "ENOENT" || error.code === "ENOTDIR") {
 225             return false;
 226         }
 227         throw error;
 228     }
 229 }
 230
 231 /**
 232  * Outputs the results of the linting.
 233  * @param {ESLint} engine The ESLint instance to use.
 234  * @param {LintResult[]} results The results to print.
 235  * @param {string} format The name of the formatter to use or the path to the formatter.
 236  * @param {string} outputFile The path for the output file.
 237  * @param {ResultsMeta} resultsMeta Warning count and max threshold.
 238  * @returns {Promise<boolean>} True if the printing succeeds, false if not.
 239  * @private
 240  */
 241 async function printResults(engine, results, format, outputFile, resultsMeta) {
 242     let formatter;
 243
 244     try {
 245         formatter = await engine.loadFormatter(format);
 246     } catch (e) {
 247         log.error(e.message);
 248         return false;
 249     }
 250
 251     const output = await formatter.format(results, resultsMeta);
 252
 253     if (output) {
 254         if (outputFile) {
 255             const filePath = path.resolve(process.cwd(), outputFile);
 256
 257             if (await isDirectory(filePath)) {
 258                 log.error("Cannot write to output file path, it is a directory: %s", outputFile);
 259                 return false;
 260             }
 261
 262             try {
 263                 await mkdir(path.dirname(filePath), { recursive: true });
 264                 await writeFile(filePath, output);
 265             } catch (ex) {
 266                 log.error("There was a problem writing the output file:\n%s", ex);
 267                 return false;
 268             }
 269         } else {
 270             log.info(output);
 271         }
 272     }
 273
 274     return true;
 275 }
 276
 277 //------------------------------------------------------------------------------
 278 // Public Interface
 279 //------------------------------------------------------------------------------
 280
 281 /**
 282  * Encapsulates all CLI behavior for eslint. Makes it easier to test as well as
 283  * for other Node.js programs to effectively run the CLI.
 284  */
 285 const cli = {
 286
 287     /**
 288      * Executes the CLI based on an array of arguments that is passed in.
 289      * @param {string|Array|Object} args The arguments to process.
 290      * @param {string} [text] The text to lint (used for TTY).
 291      * @param {boolean} [allowFlatConfig] Whether or not to allow flat config.
 292      * @returns {Promise<number>} The exit code for the operation.
 293      */
 294     async execute(args, text, allowFlatConfig) {
 295         if (Array.isArray(args)) {
 296             debug("CLI args: %o", args.slice(2));
 297         }
 298
 299         /*
 300          * Before doing anything, we need to see if we are using a
 301          * flat config file. If so, then we need to change the way command
 302          * line args are parsed. This is temporary, and when we fully
 303          * switch to flat config we can remove this logic.
 304          */
 305
 306         const usingFlatConfig = allowFlatConfig && await shouldUseFlatConfig();
 307
 308         debug("Using flat config?", usingFlatConfig);
 309
 310         const CLIOptions = createCLIOptions(usingFlatConfig);
 311
 312         /** @type {ParsedCLIOptions} */
 313         let options;
 314
 315         try {
 316             options = CLIOptions.parse(args);
 317         } catch (error) {
 318             debug("Error parsing CLI options:", error.message);
 319             log.error(error.message);
 320             return 2;
 321         }
 322
 323         const files = options._;
 324         const useStdin = typeof text === "string";
 325
 326         if (options.help) {
 327             log.info(CLIOptions.generateHelp());
 328             return 0;
 329         }
 330         if (options.version) {
 331             log.info(RuntimeInfo.version());
 332             return 0;
 333         }
 334         if (options.envInfo) {
 335             try {
 336                 log.info(RuntimeInfo.environment());
 337                 return 0;
 338             } catch (err) {
 339                 debug("Error retrieving environment info");
 340                 log.error(err.message);
 341                 return 2;
 342             }
 343         }
 344
 345         if (options.printConfig) {
 346             if (files.length) {
 347                 log.error("The --print-config option must be used with exactly one file name.");
 348                 return 2;
 349             }
 350             if (useStdin) {
 351                 log.error("The --print-config option is not available for piped-in code.");
 352                 return 2;
 353             }
 354
 355             const engine = usingFlatConfig
 356                 ? new FlatESLint(await translateOptions(options, "flat"))
 357                 : new ESLint(await translateOptions(options));
 358             const fileConfig =
 359                 await engine.calculateConfigForFile(options.printConfig);
 360
 361             log.info(JSON.stringify(fileConfig, null, "  "));
 362             return 0;
 363         }
 364
 365         debug(`Running on ${useStdin ? "text" : "files"}`);
 366
 367         if (options.fix && options.fixDryRun) {
 368             log.error("The --fix option and the --fix-dry-run option cannot be used together.");
 369             return 2;
 370         }
 371         if (useStdin && options.fix) {
 372             log.error("The --fix option is not available for piped-in code; use --fix-dry-run instead.");
 373             return 2;
 374         }
 375         if (options.fixType && !options.fix && !options.fixDryRun) {
 376             log.error("The --fix-type option requires either --fix or --fix-dry-run.");
 377             return 2;
 378         }
 379
 380         const ActiveESLint = usingFlatConfig ? FlatESLint : ESLint;
 381
 382         const engine = new ActiveESLint(await translateOptions(options, usingFlatConfig ? "flat" : "eslintrc"));
 383         let results;
 384
 385         if (useStdin) {
 386             results = await engine.lintText(text, {
 387                 filePath: options.stdinFilename,
 388                 warnIgnored: true
 389             });
 390         } else {
 391             results = await engine.lintFiles(files);
 392         }
 393
 394         if (options.fix) {
 395             debug("Fix mode enabled - applying fixes");
 396             await ActiveESLint.outputFixes(results);
 397         }
 398
 399         let resultsToPrint = results;
 400
 401         if (options.quiet) {
 402             debug("Quiet mode enabled - filtering out warnings");
 403             resultsToPrint = ActiveESLint.getErrorResults(resultsToPrint);
 404         }
 405
 406         const resultCounts = countErrors(results);
 407         const tooManyWarnings = options.maxWarnings >= 0 && resultCounts.warningCount > options.maxWarnings;
 408         const resultsMeta = tooManyWarnings
 409             ? {
 410                 maxWarningsExceeded: {
 411                     maxWarnings: options.maxWarnings,
 412                     foundWarnings: resultCounts.warningCount
 413                 }
 414             }
 415             : {};
 416
 417         if (await printResults(engine, resultsToPrint, options.format, options.outputFile, resultsMeta)) {
 418
 419             // Errors and warnings from the original unfiltered results should determine the exit code
 420             const shouldExitForFatalErrors =
 421                 options.exitOnFatalError && resultCounts.fatalErrorCount > 0;
 422
 423             if (!resultCounts.errorCount && tooManyWarnings) {
 424                 log.error(
 425                     "ESLint found too many warnings (maximum: %s).",
 426                     options.maxWarnings
 427                 );
 428             }
 429
 430             if (shouldExitForFatalErrors) {
 431                 return 2;
 432             }
 433
 434             return (resultCounts.errorCount || tooManyWarnings) ? 1 : 0;
 435         }
 436
 437         return 2;
 438     }
 439 };
 440
 441 module.exports = cli;