docs(linter): add documentation on dependency-checks rule (#17962)

docs/generated/manifests/menus.json

@@ -4881,6 +4881,14 @@
                 "isExternal": false,
                 "children": [],
                 "disableCollapsible": false
+              },
+              {
+                "name": "The `dependency-checks` rule",
+                "path": "/packages/eslint-plugin/documents/dependency-checks",
+                "id": "dependency-checks",
+                "isExternal": false,
+                "children": [],
+                "disableCollapsible": false
               }
             ],
             "isExternal": false,

docs/generated/manifests/packages.json

@@ -690,6 +690,17 @@
         "path": "/packages/eslint-plugin/documents/enforce-module-boundaries",
         "tags": [],
         "originalFilePath": "shared/packages/linter/enforce-module-boundaries"
+      },
+      "/packages/eslint-plugin/documents/dependency-checks": {
+        "id": "dependency-checks",
+        "name": "The `dependency-checks` rule",
+        "description": "The eslint-plugin package is an ESLint plugin that contains a collection of recommended ESLint rule configurations which you can extend from in your own ESLint configs, as well as an Nx-specific lint rule called enforce-module-boundaries.",
+        "file": "generated/packages/eslint-plugin/documents/dependency-checks",
+        "itemList": [],
+        "isExternal": false,
+        "path": "/packages/eslint-plugin/documents/dependency-checks",
+        "tags": [],
+        "originalFilePath": "shared/packages/linter/dependency-checks"
       }
     },
     "root": "/packages/eslint-plugin",

docs/generated/packages-metadata.json

@@ -680,6 +680,17 @@
         "path": "eslint-plugin/documents/enforce-module-boundaries",
         "tags": [],
         "originalFilePath": "shared/packages/linter/enforce-module-boundaries"
+      },
+      {
+        "id": "dependency-checks",
+        "name": "The `dependency-checks` rule",
+        "description": "The eslint-plugin package is an ESLint plugin that contains a collection of recommended ESLint rule configurations which you can extend from in your own ESLint configs, as well as an Nx-specific lint rule called enforce-module-boundaries.",
+        "file": "generated/packages/eslint-plugin/documents/dependency-checks",
+        "itemList": [],
+        "isExternal": false,
+        "path": "eslint-plugin/documents/dependency-checks",
+        "tags": [],
+        "originalFilePath": "shared/packages/linter/dependency-checks"
       }
     ],
     "executors": [],

docs/generated/packages/eslint-plugin/documents/dependency-checks.md

@@ -0,0 +1,71 @@
+# Dependency Checks rule
+
+The `@nx/dependency-checks` ESLint rule enables you to discover mismatches between dependencies specified in a project's `package.json` and the dependencies that your project depends on. If your project is using, for example, the `axios`, but the `package.json` does not specify it as a dependency, your library might not work correctly. This rule helps catch these problems before your users do.
+
+The rule uses the project graph to collect all the dependencies of your project, based on the input of your `build` target. It will filter out all the dependencies marked as `devDependencies` in your root `package.json` to ensure dependencies of your compilation pipelines (e.g. dependencies of `webpack.config` or `vite.config`) or test setups are not included in the expected list.
+
+We use the version numbers of the installed packages when checking whether the version specifier in `package.json` is correct. We do this because this is the only version for which we can "guarantee" that things work and were tested. If you specify a range outside of that version, that would mean that you are shipping potentially untested code.
+
+## Usage
+
+You can use the `dependency-checks` rule by adding it to your ESLint rules configuration:
+
+```jsonc {% fileName=".eslintrc.json" %}
+{
+  // ... more ESLint config here
+  "overrides": [
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": "error"
+      }
+    }
+    // ... more ESLint overrides here
+  ]
+}
+```
+
+Linting `JSON` files is not enabled by default, so you will also need to add `package.json` to the `lintFilePatterns`:
+
+```jsonc {% fileName="project.json" %}
+{
+  // ... project.json config
+  "targets": {
+    // ... more targets
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": [
+          "libs/my-lib/**/*.{ts,tsx,js,jsx}",
+          "libs/my-lib/package.json" // add this line
+        ]
+      }
+    }
+  }
+}
+```
+
+Sometimes we intentionally want to add or remove a dependency from our `package.json` despite what the rule suggests. We can use the rule's options to override default behavior:
+
+```jsonc {% fileName=".eslintrc.json" %}
+{
+  "@nx/dependency-checks": [
+    "error",
+    {
+      // for available options check below
+    }
+  ]
+}
+```
+
+## Options
+
+| Property                  | Type            | Default     | Description                                                             |
+| ------------------------- | --------------- | ----------- | ----------------------------------------------------------------------- |
+| buildTargets              | _Array<string>_ | _["build"]_ | List of build target names                                              |
+| ignoredDependencies       | _Array<string>_ | _[]_        | List of dependencies to ignore for checks                               |
+| checkMissingDependencies  | _boolean_       | _true_      | Disable to skip checking for missing dependencies                       |
+| checkObsoleteDependencies | _boolean_       | _true_      | Disable to skip checking for unused dependencies                        |
+| checkVersionMismatches    | _boolean_       | _true_      | Disable to skip checking if version specifier matches installed version |

docs/generated/packages/eslint-plugin/documents/enforce-module-boundaries.md

@@ -1,3 +1,5 @@
+# Enforce module boundaries rule
+
 The `@nx/enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. Enforcing strict boundaries helps to prevent unplanned cross-dependencies.
 
 ## Usage

docs/generated/packages/eslint-plugin/documents/overview.md

@@ -1,4 +1,7 @@
-The `@nx/eslint-plugin` package is an ESLint plugin that contains a collection of recommended ESLint rule configurations which you can extend from in your own ESLint configs, as well as an Nx-specific lint rule called [enforce-module-boundaries](#enforce-module-boundaries-rule).
+The `@nx/eslint-plugin` package is an ESLint plugin that contains a collection of recommended ESLint rule configurations which you can extend from in your own ESLint configs, as well as the following Nx-specific ESLint rules:
+
+- [enforce-module-boundaries](#enforce-module-boundaries-rule)
+- [dependency-checks](#dependency-checks-rule)
 
 ## Setting Up ESLint Plugin
 
@@ -54,4 +57,8 @@ You can also use `@nx/react` which includes all three `@nx/react-*` plugins
 
 ### Enforce Module Boundaries rule
 
-The `enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. Enforcing strict boundaries helps keep prevent unplanned cross-dependencies. Read more about it on a [dedicated page](/packages/eslint-plugin/documents/enforce-module-boundaries)
+The `enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. Enforcing strict boundaries helps prevent unplanned cross-dependencies. Read more about it on a [dedicated page](/packages/eslint-plugin/documents/enforce-module-boundaries).
+
+### Dependency Checks rule
+
+The `@nx/dependency-checks` ESLint rule enables you to discover mismatches between dependencies specified in a project's `package.json` and the dependencies that your project actually depends on. Read more about it on a [dedicated page](/packages/eslint-plugin/documents/dependency-checks).

docs/map.json

@@ -2062,6 +2062,12 @@
               "name": "The `enforce-module-boundaries` rule",
               "path": "/packages/eslint-plugin",
               "file": "shared/packages/linter/enforce-module-boundaries"
+            },
+            {
+              "id": "dependency-checks",
+              "name": "The `dependency-checks` rule",
+              "path": "/packages/eslint-plugin",
+              "file": "shared/packages/linter/dependency-checks"
             }
           ]
         },

docs/shared/packages/linter/dependency-checks.md

@@ -0,0 +1,71 @@
+# Dependency Checks rule
+
+The `@nx/dependency-checks` ESLint rule enables you to discover mismatches between dependencies specified in a project's `package.json` and the dependencies that your project depends on. If your project is using, for example, the `axios`, but the `package.json` does not specify it as a dependency, your library might not work correctly. This rule helps catch these problems before your users do.
+
+The rule uses the project graph to collect all the dependencies of your project, based on the input of your `build` target. It will filter out all the dependencies marked as `devDependencies` in your root `package.json` to ensure dependencies of your compilation pipelines (e.g. dependencies of `webpack.config` or `vite.config`) or test setups are not included in the expected list.
+
+We use the version numbers of the installed packages when checking whether the version specifier in `package.json` is correct. We do this because this is the only version for which we can "guarantee" that things work and were tested. If you specify a range outside of that version, that would mean that you are shipping potentially untested code.
+
+## Usage
+
+You can use the `dependency-checks` rule by adding it to your ESLint rules configuration:
+
+```jsonc {% fileName=".eslintrc.json" %}
+{
+  // ... more ESLint config here
+  "overrides": [
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": "error"
+      }
+    }
+    // ... more ESLint overrides here
+  ]
+}
+```
+
+Linting `JSON` files is not enabled by default, so you will also need to add `package.json` to the `lintFilePatterns`:
+
+```jsonc {% fileName="project.json" %}
+{
+  // ... project.json config
+  "targets": {
+    // ... more targets
+    "lint": {
+      "executor": "@nx/linter:eslint",
+      "outputs": ["{options.outputFile}"],
+      "options": {
+        "lintFilePatterns": [
+          "libs/my-lib/**/*.{ts,tsx,js,jsx}",
+          "libs/my-lib/package.json" // add this line
+        ]
+      }
+    }
+  }
+}
+```
+
+Sometimes we intentionally want to add or remove a dependency from our `package.json` despite what the rule suggests. We can use the rule's options to override default behavior:
+
+```jsonc {% fileName=".eslintrc.json" %}
+{
+  "@nx/dependency-checks": [
+    "error",
+    {
+      // for available options check below
+    }
+  ]
+}
+```
+
+## Options
+
+| Property                  | Type            | Default     | Description                                                             |
+| ------------------------- | --------------- | ----------- | ----------------------------------------------------------------------- |
+| buildTargets              | _Array<string>_ | _["build"]_ | List of build target names                                              |
+| ignoredDependencies       | _Array<string>_ | _[]_        | List of dependencies to ignore for checks                               |
+| checkMissingDependencies  | _boolean_       | _true_      | Disable to skip checking for missing dependencies                       |
+| checkObsoleteDependencies | _boolean_       | _true_      | Disable to skip checking for unused dependencies                        |
+| checkVersionMismatches    | _boolean_       | _true_      | Disable to skip checking if version specifier matches installed version |

docs/shared/packages/linter/enforce-module-boundaries.md

@@ -1,3 +1,5 @@
+# Enforce module boundaries rule
+
 The `@nx/enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. Enforcing strict boundaries helps to prevent unplanned cross-dependencies.
 
 ## Usage

docs/shared/packages/linter/eslint-plugin.md

@@ -1,4 +1,7 @@
-The `@nx/eslint-plugin` package is an ESLint plugin that contains a collection of recommended ESLint rule configurations which you can extend from in your own ESLint configs, as well as an Nx-specific lint rule called [enforce-module-boundaries](#enforce-module-boundaries-rule).
+The `@nx/eslint-plugin` package is an ESLint plugin that contains a collection of recommended ESLint rule configurations which you can extend from in your own ESLint configs, as well as the following Nx-specific ESLint rules:
+
+- [enforce-module-boundaries](#enforce-module-boundaries-rule)
+- [dependency-checks](#dependency-checks-rule)
 
 ## Setting Up ESLint Plugin
 
@@ -54,4 +57,8 @@ You can also use `@nx/react` which includes all three `@nx/react-*` plugins
 
 ### Enforce Module Boundaries rule
 
-The `enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. Enforcing strict boundaries helps keep prevent unplanned cross-dependencies. Read more about it on a [dedicated page](/packages/eslint-plugin/documents/enforce-module-boundaries)
+The `enforce-module-boundaries` ESLint rule enables you to define strict rules for accessing resources between different projects in the repository. Enforcing strict boundaries helps prevent unplanned cross-dependencies. Read more about it on a [dedicated page](/packages/eslint-plugin/documents/enforce-module-boundaries).
+
+### Dependency Checks rule
+
+The `@nx/dependency-checks` ESLint rule enables you to discover mismatches between dependencies specified in a project's `package.json` and the dependencies that your project actually depends on. Read more about it on a [dedicated page](/packages/eslint-plugin/documents/dependency-checks).

docs/shared/reference/sitemap.md

@@ -358,6 +358,7 @@
     - [documents](/packages/eslint-plugin/documents)
       - [Overview](/packages/eslint-plugin/documents/overview)
       - [The `enforce-module-boundaries` rule](/packages/eslint-plugin/documents/enforce-module-boundaries)
+      - [The `dependency-checks` rule](/packages/eslint-plugin/documents/dependency-checks)
   - [expo](/packages/expo)
     - [documents](/packages/expo/documents)
       - [Overview](/packages/expo/documents/overview)