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