docs: Integration section and tutorial (#17132)

* docs: Integration section and tutorial

* add navigation and landing pages for integration section

* copy edits

* working sample rule

* complete integration tutorial draft

* remove TODO

* Apply suggestions from code review

Co-authored-by: Nicholas C. Zakas <[email protected]>

* update source code

* update tutorial

* copy / linting edits

* lint fix

* Apply suggestions from code review

Co-authored-by: Nicholas C. Zakas <[email protected]>

* implement nz feedback

* Copy edit

* Apply suggestions from code review

Co-authored-by: Nitin Kumar <[email protected]>

* Apply suggestions from code review

Co-authored-by: Milos Djermanovic <[email protected]>

* Apply suggestions from code review

Co-authored-by: Milos Djermanovic <[email protected]>

* implement MD feedback

* copy edit

---------

Co-authored-by: Nicholas C. Zakas <[email protected]>
Co-authored-by: Nitin Kumar <[email protected]>
Co-authored-by: Milos Djermanovic <[email protected]>

Author: 4 people

docs/_examples/integration-tutorial-code/.gitignore

@@ -0,0 +1,2 @@
+node_modules
+.DS_Store

docs/_examples/integration-tutorial-code/example-eslint-integration.js

@@ -0,0 +1,62 @@
+/** 
+ * @fileoverview An example of how to integrate ESLint into your own tool
+ * @author Ben Perlmutter
+ */
+
+const { ESLint } = require("eslint");
+
+// Create an instance of ESLint with the configuration passed to the function
+function createESLintInstance(overrideConfig){
+  return new ESLint({ useEslintrc: false, overrideConfig: overrideConfig, fix: true });
+}
+
+// Lint the specified files and return the error results
+async function lintAndFix(eslint, filePaths) {
+  const results = await eslint.lintFiles(filePaths);
+
+  // Apply automatic fixes and output fixed code
+  await ESLint.outputFixes(results);
+
+  return results;
+}
+
+// Log results to console if there are any problems
+function outputLintingResults(results) {
+  // Identify the number of problems found
+  const problems = results.reduce((acc, result) => acc + result.errorCount + result.warningCount, 0);
+
+  if (problems > 0) {
+    console.log("Linting errors found!");
+    console.log(results);
+  } else {
+    console.log("No linting errors found.");
+  }
+  return results;
+}
+
+// Put previous functions all together
+async function lintFiles(filePaths) {
+
+    // The ESLint configuration. Alternatively, you could load the configuration
+    // from a .eslintrc file or just use the default config.
+    const overrideConfig = {
+        env: {
+            es6: true,
+            node: true,
+        },
+        parserOptions: {
+            ecmaVersion: 2018,
+        },
+        rules: {
+            "no-console": "error",
+            "no-unused-vars": "warn",
+        },
+    };
+
+    const eslint = createESLintInstance(overrideConfig);
+    const results = await lintAndFix(eslint, filePaths);
+    return outputLintingResults(results);
+}
+
+// Export integration
+module.exports = { lintFiles }

docs/_examples/integration-tutorial-code/example-eslint-integration.test.js

@@ -0,0 +1,27 @@
+/**
+ * @fileoverview Test ESLint integration example code
+ * @author Ben Perlmutter
+ */
+
+const { lintFiles } = require("./example-eslint-integration");
+
+async function testExampleEslintIntegration(){
+    const filePaths = ["sample-data/test-file.js"];
+    const lintResults = await lintFiles(filePaths);
+
+    // Test cases
+    if(lintResults[0].messages.length !== 6){
+        throw new Error("Expected 6 linting problems, got " + lintResults[0].messages.length);
+    }
+    const messageRuleIds = new Set()
+    lintResults[0].messages.forEach(msg => messageRuleIds.add(msg.ruleId));
+    if(messageRuleIds.size !== 2){
+        throw new Error("Expected 2 linting rule, got " + messageRuleIds.size);
+    }
+    if(!messageRuleIds.has("no-console")){
+        throw new Error("Expected linting rule 'no-console', got " + messageRuleIds);
+    }
+    console.log("All tests passed!");
+}
+
+testExampleEslintIntegration()

docs/_examples/integration-tutorial-code/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "_integration-tutorial-code",
+  "version": "1.0.0",
+  "description": "",
+  "main": "index.js",
+  "scripts": {
+    "test": "node example-eslint-integration.test.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "eslint": "^8.39.0"
+  }
+}

docs/_examples/integration-tutorial-code/sample-data/test-file.js

@@ -0,0 +1,29 @@
+/** 
+ * @fileoverview Example data to lint using ESLint. This file contains a variety of errors.
+ * @author Ben Perlmutter
+ */
+
+// Unused variable 'y' (no-unused-vars from configured rules)
+const y = 20;
+
+function add(a, b) {
+  // Unexpected console statement (no-console from configured rules)
+  console.log('Adding two numbers');
+  return a + b;
+}
+
+// 'result' is assigned a value but never used (no-unused-vars from configured rules)
+const result = add(x, 5);
+
+if (x > 5) {
+    // Unexpected console statement (no-console from configured rules)
+    console.log('x is greater than 5');
+} else {
+    // Unexpected console statement (no-console from configured rules)
+    console.log('x is not greater than 5');
+}
+
+// 'subtract' is defined but never used (no-unused-vars from configured rules)
+function subtract(a, b) {
+  return a - b;
+}

docs/src/contribute/index.md

@@ -3,7 +3,7 @@ title: Contribute to ESLint
 eleventyNavigation:
     key: contribute to eslint
     title: Contribute to ESLint
-    order: 3
+    order: 4
 ---
 
 One of the great things about open source projects is that anyone can contribute in any number of meaningful ways. ESLint couldn't exist without the help of the many contributors it's had since the project began, and we want you to feel like you can contribute and make a difference as well.

docs/src/extend/index.md

@@ -48,7 +48,3 @@ This section explains how you can use a custom processor to have ESLint process
 ## [Share Configurations](shareable-configs)
 
 This section explains how you can bundle and share ESLint configuration in a JavaScript package.
-
-## [Node.js API Reference](../integrate/nodejs-api)
-
-If you're interested in writing a tool that uses ESLint, then you can use the Node.js API to get programmatic access to functionality.

docs/src/integrate/index.md

@@ -0,0 +1,25 @@
+---
+title: Integrate ESLint
+eleventyNavigation:
+    key: integrate eslint
+    title: integrate ESLint
+    order: 3
+
+---
+
+This guide is intended for those who wish to integrate the functionality of ESLint into other applications by using the ESLint API.
+
+In order to integrate ESLint, it's recommended that:
+
+* You know JavaScript since ESLint is written in JavaScript.
+* You have some familiarity with Node.js since ESLint runs on it.
+
+If that sounds like you, then continue reading to get started.
+
+## [Integrate with the Node.js API Tutorial](integration-tutorial)
+
+This tutorial walks you through the process of creating a basic integration with ESLint using the Node.js API.
+
+## [Node.js API Reference](nodejs-api)
+
+If you're interested in writing a tool that uses ESLint, then you can use the Node.js API to get programmatic access to functionality.