feat(valid-package-definition): rename rule from valid-package-def (#711

)  ## PR Checklist - [x] Addresses an existing open issue: fixes #132 - [x] That issue was marked as [`status: accepting prs`](https://github.com/JoshuaKGoldberg/eslint-plugin-package-json/issues?q=is%3Aopen+is%3Aissue+label%3A%22status%3A+accepting+prs%22) - [x] Steps in [CONTRIBUTING.md](https://github.com/JoshuaKGoldberg/eslint-plugin-package-json/blob/main/.github/CONTRIBUTING.md) were taken ## Overview This change deprecates the `valid-package-def` rule in favor of a new `valid-package-definition` rule, providing the same behavior. The deprecated version of the rule will be removed in the next major release. I assumed you wanted to roll this change out in a non-breaking way initially? If that's not the case and you want to major, I can remove the deprecated rule. If you do prefer this approach, then it may be worth documenting the follow-up so that when it's time to major, the deprecated rule is dropped? Closes #132
JoshuaKGoldberg · Dec 31, 2024 · 4f3907b · 4f3907b
1 parent cd165ae
commit 4f3907b
Show file tree

Hide file tree

Showing 6 changed files with 92 additions and 21 deletions.
diff --git a/README.md b/README.md
@@ -53,7 +53,7 @@ export default [
 		...packageJson,
 		rules: {
 			...packageJson.rules,
-			"package-json/valid-package-def": "off",
+			"package-json/valid-package-definition": "off",
 		},
 	},
 ];
@@ -96,7 +96,7 @@ module.exports = {
 			parser: "jsonc-eslint-parser",
 			plugins: ["package-json"],
 			rules: {
-				"package-json/valid-package-def": "error",
+				"package-json/valid-package-definition": "error",
 			},
 		},
 	],
@@ -117,19 +117,21 @@ The default settings don't conflict, and Prettier plugins can quickly fix up ord
 💼 Configurations enabled in.\
 ✅ Set in the `recommended` configuration.\
 🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
-💡 Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
-
-| Name                                                                   | Description                                                                                       | 💼 | 🔧 | 💡 |
-| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :- | :- | :- |
-| [order-properties](docs/rules/order-properties.md)                     | Package properties must be declared in standard order                                             | ✅  | 🔧 |    |
-| [repository-shorthand](docs/rules/repository-shorthand.md)             | Enforce either object or shorthand declaration for repository.                                    | ✅  | 🔧 |    |
-| [sort-collections](docs/rules/sort-collections.md)                     | Dependencies, scripts, and configuration values must be declared in alphabetical order.           | ✅  | 🔧 |    |
-| [unique-dependencies](docs/rules/unique-dependencies.md)               | Checks a dependency isn't specified more than once (i.e. in `dependencies` and `devDependencies`) | ✅  |    | 💡 |
-| [valid-local-dependency](docs/rules/valid-local-dependency.md)         | Checks existence of local dependencies in the package.json                                        | ✅  |    |    |
-| [valid-name](docs/rules/valid-name.md)                                 | Enforce that package names are valid npm package names                                            | ✅  |    |    |
-| [valid-package-def](docs/rules/valid-package-def.md)                   | Enforce that package.json has all properties required by the npm spec                             | ✅  |    |    |
-| [valid-repository-directory](docs/rules/valid-repository-directory.md) | Enforce that if repository directory is specified, it matches the path to the package.json file   | ✅  |    | 💡 |
-| [valid-version](docs/rules/valid-version.md)                           | Enforce that package versions are valid semver specifiers                                         | ✅  |    |    |
+💡 Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).\
+❌ Deprecated.
+
+| Name                                                                   | Description                                                                                       | 💼 | 🔧 | 💡 | ❌  |
+| :--------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :- | :- | :- | :- |
+| [order-properties](docs/rules/order-properties.md)                     | Package properties must be declared in standard order                                             | ✅  | 🔧 |    |    |
+| [repository-shorthand](docs/rules/repository-shorthand.md)             | Enforce either object or shorthand declaration for repository.                                    | ✅  | 🔧 |    |    |
+| [sort-collections](docs/rules/sort-collections.md)                     | Dependencies, scripts, and configuration values must be declared in alphabetical order.           | ✅  | 🔧 |    |    |
+| [unique-dependencies](docs/rules/unique-dependencies.md)               | Checks a dependency isn't specified more than once (i.e. in `dependencies` and `devDependencies`) | ✅  |    | 💡 |    |
+| [valid-local-dependency](docs/rules/valid-local-dependency.md)         | Checks existence of local dependencies in the package.json                                        | ✅  |    |    |    |
+| [valid-name](docs/rules/valid-name.md)                                 | Enforce that package names are valid npm package names                                            | ✅  |    |    |    |
+| [valid-package-def](docs/rules/valid-package-def.md)                   | Enforce that package.json has all properties required by the npm spec                             |    |    |    | ❌  |
+| [valid-package-definition](docs/rules/valid-package-definition.md)     | Enforce that package.json has all properties required by the npm spec                             | ✅  |    |    |    |
+| [valid-repository-directory](docs/rules/valid-repository-directory.md) | Enforce that if repository directory is specified, it matches the path to the package.json file   | ✅  |    | 💡 |    |
+| [valid-version](docs/rules/valid-version.md)                           | Enforce that package versions are valid semver specifiers                                         | ✅  |    |    |    |
 
 <!-- end auto-generated rules list -->
 <!-- prettier-ignore-end -->

diff --git a/docs/rules/valid-package-def.md b/docs/rules/valid-package-def.md
@@ -1,6 +1,6 @@
 # valid-package-def
 
-💼 This rule is enabled in the ✅ `recommended` config.
+❌ This rule is deprecated. It was replaced by [`package-json/valid-package-definition`](valid-package-definition.md).
 
 <!-- end auto-generated rule header -->
 

diff --git a/docs/rules/valid-package-definition.md b/docs/rules/valid-package-definition.md
@@ -0,0 +1,54 @@
+# valid-package-definition
+
+💼 This rule is enabled in the ✅ `recommended` config.
+
+<!-- end auto-generated rule header -->
+
+npm issues warnings after install if the `package.json` has a missing or invalid required property.
+This rule uses [`package-json-validator`][pjv] to validate all `package.json` files against the [npm specification][npm-spec], and add any violations to lint warnings.
+
+## Rule Details
+
+This rule aims to ensure that `package.json` complies with specifications.
+
+Examples of **incorrect** code for this rule:
+
+```json
+{
+	"author": "",
+	"description": "",
+	"keywords": [],
+	"license": "ISC",
+	"main": "index.js",
+	"name": "noncompliant-version",
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"version": "1.X.0"
+}
+```
+
+Examples of **correct** code for this rule:
+
+```json
+{
+	"author": "",
+	"description": "",
+	"keywords": [],
+	"license": "ISC",
+	"main": "index.js",
+	"name": "compliant-version",
+	"scripts": {
+		"test": "echo \"Error: no test specified\" && exit 1"
+	},
+	"version": "1.0.0"
+}
+```
+
+## When Not To Use It
+
+npm may complain, but it works perfectly with many package files that do not violate spec.
+If you don't mind those complaints then you can disable this rule.
+
+[pjv]: https://github.com/gorillamania/package.json-validator
+[npm-spec]: https://docs.npmjs.com/files/package.json
diff --git a/src/plugin.ts b/src/plugin.ts
@@ -1,12 +1,14 @@
 import { createRequire } from "node:module";
 
+import type { PackageJsonRuleModule } from "./createRule.js";
+
 import { rule as orderProperties } from "./rules/order-properties.js";
 import { rule as preferRepositoryShorthand } from "./rules/repository-shorthand.js";
 import { rule as sortCollections } from "./rules/sort-collections.js";
 import { rule as uniqueDependencies } from "./rules/unique-dependencies.js";
 import { rule as validLocalDependency } from "./rules/valid-local-dependency.js";
 import { rule as validName } from "./rules/valid-name.js";
-import { rule as validPackageDef } from "./rules/valid-package-def.js";
+import { rule as validPackageDefinition } from "./rules/valid-package-definition.js";
 import { rule as validRepositoryDirectory } from "./rules/valid-repository-directory.js";
 import { rule as validVersion } from "./rules/valid-version.js";
 
@@ -17,14 +19,27 @@ const { name, version } = require("../package.json") as {
 	version: string;
 };
 
-const rules = {
+const rules: Record<string, PackageJsonRuleModule> = {
 	"order-properties": orderProperties,
 	"repository-shorthand": preferRepositoryShorthand,
 	"sort-collections": sortCollections,
 	"unique-dependencies": uniqueDependencies,
 	"valid-local-dependency": validLocalDependency,
 	"valid-name": validName,
-	"valid-package-def": validPackageDef,
+	/** @deprecated use 'valid-package-definition' instead */
+	"valid-package-def": {
+		...validPackageDefinition,
+		meta: {
+			...validPackageDefinition.meta,
+			deprecated: true,
+			docs: {
+				...validPackageDefinition.meta.docs,
+				recommended: false,
+			},
+			replacedBy: ["valid-package-definition"],
+		},
+	},
+	"valid-package-definition": validPackageDefinition,
 	"valid-repository-directory": validRepositoryDirectory,
 	"valid-version": validVersion,
 };

diff --git a/src/rules/valid-package-def.ts → src/rules/valid-package-definition.ts b/src/rules/valid-package-def.ts → src/rules/valid-package-definition.ts
diff --git a/src/tests/rules/valid-package-def.test.ts → ...ts/rules/valid-package-definition.test.ts b/src/tests/rules/valid-package-def.test.ts → ...ts/rules/valid-package-definition.test.ts
@@ -1,7 +1,7 @@
-import { rule } from "../../rules/valid-package-def.js";
+import { rule } from "../../rules/valid-package-definition.js";
 import { ruleTester } from "./ruleTester.js";
 
-ruleTester.run("valid-package-def", rule, {
+ruleTester.run("valid-package-definition", rule, {
 	invalid: [
 		{
 			code: `{ "mane": "invalid-package" }`,