From 5af5e6ca91eca112d3dc0cf89565284575749135 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miroslav=20Jona=C5=A1?= Date: Fri, 7 Jul 2023 03:01:49 +0200 Subject: [PATCH] docs(linter): add documentation on dependency-checks rule (#17962) --- docs/generated/manifests/menus.json | 8 +++ docs/generated/manifests/packages.json | 11 +++ docs/generated/packages-metadata.json | 11 +++ .../documents/dependency-checks.md | 71 +++++++++++++++++++ .../documents/enforce-module-boundaries.md | 2 + .../eslint-plugin/documents/overview.md | 11 ++- docs/map.json | 6 ++ .../packages/linter/dependency-checks.md | 71 +++++++++++++++++++ .../linter/enforce-module-boundaries.md | 2 + docs/shared/packages/linter/eslint-plugin.md | 11 ++- docs/shared/reference/sitemap.md | 1 + 11 files changed, 201 insertions(+), 4 deletions(-) create mode 100644 docs/generated/packages/eslint-plugin/documents/dependency-checks.md create mode 100644 docs/shared/packages/linter/dependency-checks.md diff --git a/docs/generated/manifests/menus.json b/docs/generated/manifests/menus.json index e8d3610b0fa04..8f3fb2d28b032 100644 --- a/docs/generated/manifests/menus.json +++ b/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, diff --git a/docs/generated/manifests/packages.json b/docs/generated/manifests/packages.json index f8117f2c9464f..cf9da9f004552 100644 --- a/docs/generated/manifests/packages.json +++ b/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", diff --git a/docs/generated/packages-metadata.json b/docs/generated/packages-metadata.json index 406d9b0d5d290..6efa02fb1bf79 100644 --- a/docs/generated/packages-metadata.json +++ b/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": [], diff --git a/docs/generated/packages/eslint-plugin/documents/dependency-checks.md b/docs/generated/packages/eslint-plugin/documents/dependency-checks.md new file mode 100644 index 0000000000000..c905320bf852e --- /dev/null +++ b/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_ | _["build"]_ | List of build target names | +| ignoredDependencies | _Array_ | _[]_ | 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 | diff --git a/docs/generated/packages/eslint-plugin/documents/enforce-module-boundaries.md b/docs/generated/packages/eslint-plugin/documents/enforce-module-boundaries.md index 17df00f19fed5..4d8061b492eb9 100644 --- a/docs/generated/packages/eslint-plugin/documents/enforce-module-boundaries.md +++ b/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 diff --git a/docs/generated/packages/eslint-plugin/documents/overview.md b/docs/generated/packages/eslint-plugin/documents/overview.md index 7c966c2c24aba..7b00732054f64 100644 --- a/docs/generated/packages/eslint-plugin/documents/overview.md +++ b/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). diff --git a/docs/map.json b/docs/map.json index a5cf73848c8c8..de3bc1853a0c5 100644 --- a/docs/map.json +++ b/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" } ] }, diff --git a/docs/shared/packages/linter/dependency-checks.md b/docs/shared/packages/linter/dependency-checks.md new file mode 100644 index 0000000000000..c905320bf852e --- /dev/null +++ b/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_ | _["build"]_ | List of build target names | +| ignoredDependencies | _Array_ | _[]_ | 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 | diff --git a/docs/shared/packages/linter/enforce-module-boundaries.md b/docs/shared/packages/linter/enforce-module-boundaries.md index 17df00f19fed5..4d8061b492eb9 100644 --- a/docs/shared/packages/linter/enforce-module-boundaries.md +++ b/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 diff --git a/docs/shared/packages/linter/eslint-plugin.md b/docs/shared/packages/linter/eslint-plugin.md index 7c966c2c24aba..7b00732054f64 100644 --- a/docs/shared/packages/linter/eslint-plugin.md +++ b/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). diff --git a/docs/shared/reference/sitemap.md b/docs/shared/reference/sitemap.md index 9c5f17bca2529..d1a8b24fcdd01 100644 --- a/docs/shared/reference/sitemap.md +++ b/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)