Update: Add ESLint API (refs eslint/rfcs#40) (#12939)

* Update: Add ESLint API

* Refactor

* Address feedback

* Make CLIEngine instance a private property

* Validate plugin objects

* Add test clarifying CLIEngine extensions behavior

* Add lintText() tests

* Add lintFiles() tests

* update usedDeprecatedRules property

* update around loadFormatter

* fix usedDeprecatedRules

* fix a bug about addPlugin method

* improve validation

* change constructor options

* add errorOnUnmatchedPattern and etc

- remove overrideConfigFile
- improve overrideConfig

* update bin/eslint.js and cli.js to use ESLint class

* rewrite tests

* fix tests

* remove compareResultsByFilePath

* fix tests

* fix tests

* remove deprecated source property

* expose the new ESLint class

* update nodejs-api.md

* fix links

* fix links

* Revert "remove deprecated source property"

This reverts commit 8421fb3.

* add author

* fix typo

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* add `LintResult#source` to docs

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Nicholas C. Zakas <nicholas@nczconsulting.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Nicholas C. Zakas <nicholas@nczconsulting.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Nicholas C. Zakas <nicholas@nczconsulting.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Nicholas C. Zakas <nicholas@nczconsulting.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Nicholas C. Zakas <nicholas@nczconsulting.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update lib/eslint/eslint.js

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update lib/eslint/eslint.js

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update tests/lib/cli.js

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Nicholas C. Zakas <nicholas@nczconsulting.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Nicholas C. Zakas <nicholas@nczconsulting.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Nicholas C. Zakas <nicholas@nczconsulting.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Kai Cataldo <kai@kaicataldo.com>

* add loadFormatter description

* add about <text>

* fix error message

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

* Update docs/developer-guide/nodejs-api.md

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

* Update lib/cli-engine/cli-engine.js

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

* Update tests/lib/cli.js

Co-Authored-By: Brandon Mills <btmills@users.noreply.github.com>

Co-authored-by: Toru Nagashima <public@mysticatea.dev>
Co-authored-by: Nicholas C. Zakas <nicholas@nczconsulting.com>
Co-authored-by: Brandon Mills <btmills@users.noreply.github.com>

bin/eslint.js

@@ -12,97 +12,135 @@
 // to use V8's code cache to speed up instantiation time
 require("v8-compile-cache");
 
-//------------------------------------------------------------------------------
-// Helpers
-//------------------------------------------------------------------------------
-
-const useStdIn = process.argv.includes("--stdin"),
-    init = process.argv.includes("--init"),
-    debug = process.argv.includes("--debug");
-
 // must do this initialization *before* other requires in order to work
-if (debug) {
+if (process.argv.includes("--debug")) {
     require("debug").enable("eslint:*,-eslint:code-path");
 }
 
 //------------------------------------------------------------------------------
-// Requirements
+// Helpers
 //------------------------------------------------------------------------------
 
-// now we can safely include the other modules that use debug
-const path = require("path"),
-    fs = require("fs"),
-    cli = require("../lib/cli");
-
-//------------------------------------------------------------------------------
-// Execution
-//------------------------------------------------------------------------------
+/**
+ * Read data from stdin til the end.
+ *
+ * Note: See
+ * - https://github.com/nodejs/node/blob/master/doc/api/process.md#processstdin
+ * - https://github.com/nodejs/node/blob/master/doc/api/process.md#a-note-on-process-io
+ * - https://lists.gnu.org/archive/html/bug-gnu-emacs/2016-01/msg00419.html
+ * - https://github.com/nodejs/node/issues/7439 (historical)
+ *
+ * On Windows using `fs.readFileSync(STDIN_FILE_DESCRIPTOR, "utf8")` seems
+ * to read 4096 bytes before blocking and never drains to read further data.
+ *
+ * The investigation on the Emacs thread indicates:
+ *
+ * > Emacs on MS-Windows uses pipes to communicate with subprocesses; a
+ * > pipe on Windows has a 4K buffer. So as soon as Emacs writes more than
+ * > 4096 bytes to the pipe, the pipe becomes full, and Emacs then waits for
+ * > the subprocess to read its end of the pipe, at which time Emacs will
+ * > write the rest of the stuff.
+ * @returns {Promise<string>} The read text.
+ */
+function readStdin() {
+    return new Promise((resolve, reject) => {
+        let content = "";
+        let chunk = "";
+
+        process.stdin
+            .setEncoding("utf8")
+            .on("readable", () => {
+                while ((chunk = process.stdin.read()) !== null) {
+                    content += chunk;
+                }
+            })
+            .on("end", () => resolve(content))
+            .on("error", reject);
+    });
+}
 
-process.once("uncaughtException", err => {
+/**
+ * Get the error message of a given value.
+ * @param {any} error The value to get.
+ * @returns {string} The error message.
+ */
+function getErrorMessage(error) {
 
-    // lazy load
+    // Lazy loading because those are used only if error happened.
+    const fs = require("fs");
+    const path = require("path");
+    const util = require("util");
     const lodash = require("lodash");
 
-    if (typeof err.messageTemplate === "string" && err.messageTemplate.length > 0) {
-        const template = lodash.template(fs.readFileSync(path.resolve(__dirname, `../messages/${err.messageTemplate}.txt`), "utf-8"));
-        const pkg = require("../package.json");
+    // Foolproof -- thirdparty module might throw non-object.
+    if (typeof error !== "object" || error === null) {
+        return String(error);
+    }
+
+    // Use templates if `error.messageTemplate` is present.
+    if (typeof error.messageTemplate === "string") {
+        try {
+            const templateFilePath = path.resolve(
+                __dirname,
+                `../messages/${error.messageTemplate}.txt`
+            );
+
+            // Use sync API because Node.js should exit at this tick.
+            const templateText = fs.readFileSync(templateFilePath, "utf-8");
+            const template = lodash.template(templateText);
+
+            return template(error.messageData || {});
+        } catch {
+
+            // Ignore template error then fallback to use `error.stack`.
+        }
+    }
 
-        console.error("\nOops! Something went wrong! :(");
-        console.error(`\nESLint: ${pkg.version}.\n\n${template(err.messageData || {})}`);
-    } else {
-        console.error(err.stack);
+    // Use the stacktrace if it's an error object.
+    if (typeof error.stack === "string") {
+        return error.stack;
     }
 
+    // Otherwise, dump the object.
+    return util.format("%o", error);
+}
+
+/**
+ * Catch and report unexpected error.
+ * @param {any} error The thrown error object.
+ * @returns {void}
+ */
+function onFatalError(error) {
     process.exitCode = 2;
-});
-
-if (useStdIn) {
-
-    /*
-     * Note: See
-     * - https://github.com/nodejs/node/blob/master/doc/api/process.md#processstdin
-     * - https://github.com/nodejs/node/blob/master/doc/api/process.md#a-note-on-process-io
-     * - https://lists.gnu.org/archive/html/bug-gnu-emacs/2016-01/msg00419.html
-     * - https://github.com/nodejs/node/issues/7439 (historical)
-     *
-     * On Windows using `fs.readFileSync(STDIN_FILE_DESCRIPTOR, "utf8")` seems
-     * to read 4096 bytes before blocking and never drains to read further data.
-     *
-     * The investigation on the Emacs thread indicates:
-     *
-     * > Emacs on MS-Windows uses pipes to communicate with subprocesses; a
-     * > pipe on Windows has a 4K buffer. So as soon as Emacs writes more than
-     * > 4096 bytes to the pipe, the pipe becomes full, and Emacs then waits for
-     * > the subprocess to read its end of the pipe, at which time Emacs will
-     * > write the rest of the stuff.
-     *
-     * Using the nodejs code example for reading from stdin.
-     */
-    let contents = "",
-        chunk = "";
-
-    process.stdin.setEncoding("utf8");
-    process.stdin.on("readable", () => {
-
-        // Use a loop to make sure we read all available data.
-        while ((chunk = process.stdin.read()) !== null) {
-            contents += chunk;
-        }
-    });
 
-    process.stdin.on("end", () => {
-        process.exitCode = cli.execute(process.argv, contents, "utf8");
-    });
-} else if (init) {
-    const configInit = require("../lib/init/config-initializer");
-
-    configInit.initializeConfig().then(() => {
-        process.exitCode = 0;
-    }).catch(err => {
-        process.exitCode = 1;
-        console.error(err.message);
-        console.error(err.stack);
-    });
-} else {
-    process.exitCode = cli.execute(process.argv);
+    const { version } = require("../package.json");
+    const message = getErrorMessage(error);
+
+    console.error(`
+Oops! Something went wrong! :(
+
+ESLint: ${version}
+
+${message}`);
 }
+
+//------------------------------------------------------------------------------
+// Execution
+//------------------------------------------------------------------------------
+
+(async function main() {
+    process.on("uncaughtException", onFatalError);
+    process.on("unhandledRejection", onFatalError);
+
+    // Call the config initializer if `--init` is present.
+    if (process.argv.includes("--init")) {
+        await require("../lib/init/config-initializer").initializeConfig();
+        return;
+    }
+
+    // Otherwise, call the CLI.
+    process.exitCode = await require("../lib/cli").execute(
+        process.argv,
+        process.argv.includes("--stdin") ? await readStdin() : null
+    );
+}()).catch(onFatalError);