eslint-plugin-package-json 0.3.1 → 0.3.2

package/.github/workflows/lint-eslint-docs.yml

@@ -0,0 +1,16 @@
+jobs:
+  tsc:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: ./.github/actions/prepare
+      - run: npm run tsc
+      - run: npm run lint:eslint-docs
+
+name: Lint ESLint Docs
+
+on:
+  pull_request: ~
+  push:
+    branches:
+      - main

package/README.md

@@ -52,10 +52,18 @@ module.exports = {
 
 ## Supported Rules
 
--   [`package-json/order-properties`](docs/rules/order-properties.md): Require top-level properties to be in a conventional order (`"name"`first, etc.).
--   [`package-json/sort-collections`](docs/rules/sort-collections.md): Keep sub-collections like `"dependencies"` and `"scripts"` in alphabetical order.
--   [`package-json/valid-package-def`](docs/rules/valid-package-def.md): Validate `package.json` files against the NPM specification.
--   [`package-json/valid-local-dependency`](docs/rules/valid-local-dependency.md): Validates the casing for `file:` and `link:` dependencies in the `package.json` files.
+<!-- begin auto-generated rules list -->
+
+🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).
+
+| Name                                                           | Description                                                                             | 🔧 |
+| :------------------------------------------------------------- | :-------------------------------------------------------------------------------------- | :- |
+| [order-properties](docs/rules/order-properties.md)             | Package properties must be declared in standard order                                   | 🔧 |
+| [sort-collections](docs/rules/sort-collections.md)             | Dependencies, scripts, and configuration values must be declared in alphabetical order. | 🔧 |
+| [valid-local-dependency](docs/rules/valid-local-dependency.md) | Checks existence of local dependencies in the package.json                              |    |
+| [valid-package-def](docs/rules/valid-package-def.md)           | Enforce that package.json has all properties required by NPM spec                       |    |
+
+<!-- end auto-generated rules list -->
 
 These rules only run on `package.json` files; they will ignore all other files being linted. They lint `package.json` files at project root, and in any subfolder of the project, making this plugin great for monorepos.
 

package/docs/rules/order-properties.md

@@ -1,4 +1,8 @@
-# Package properties must be declared in standard order (order-properties)
+# Package properties must be declared in standard order (`package-json/order-properties`)
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
 
 A conventional order exists for `package.json` top-level properties. NPM does
 not enforce this order, but for consistency and readability, this rule can

package/docs/rules/sort-collections.md

@@ -1,4 +1,8 @@
-# Dependencies, scripts, and configuration values must be declared in alphabetical order. (sort-collections)
+# Dependencies, scripts, and configuration values must be declared in alphabetical order (`package-json/sort-collections`)
+
+🔧 This rule is automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/latest/user-guide/command-line-interface#--fix).
+
+<!-- end auto-generated rule header -->
 
 Whenever NPM changes package dependencies through `npm install`, it lexically sorts (that is, alphabetizes by package name) all dependencies in `package.json`. Nevertheless, sometimes a developer will manually update `package.json` and leave dependencies out of order, leading to "noise" in changesets when a later change re-sorts the packages. This rule aims to keep the dependency collections sorted in every commit.
 

package/docs/rules/valid-local-dependency.md

@@ -1,4 +1,6 @@
-# Ensures that local dependencies specified in a package.json exist
+# Checks existence of local dependencies in the package.json (`package-json/valid-local-dependency`)
+
+<!-- end auto-generated rule header -->
 
 ## Rule Details
 
@@ -19,7 +21,3 @@ Examples of **correct** code for this rule:
             "some-package": "link:../folder",
     }
 ```
-
-### Options
-
-This rule has no options.

package/docs/rules/valid-package-def.md

@@ -1,4 +1,6 @@
-# Enforce that package.json has all properties required by NPM spec (valid-package-def)
+# Enforce that package.json has all properties required by NPM spec (`package-json/valid-package-def`)
+
+<!-- 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
@@ -43,10 +45,6 @@ Examples of **correct** code for this rule:
 }
 ```
 
-### Options
-
-This rule has no options.
-
 ## When Not To Use It
 
 NPM may complain, but it works perfectly with many package files that do not

package/lib/createRule.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createRule = void 0;
+const isPackageJson = (filePath) => filePath.endsWith('/package.json') || filePath === 'package.json';
+function createRule(rule) {
+    return {
+        ...rule,
+        create(context) {
+            if (!isPackageJson(context.filename)) {
+                return {};
+            }
+            return rule.create(context);
+        }
+    };
+}
+exports.createRule = createRule;

package/lib/index.d.ts

@@ -1,2 +1,41 @@
-export {};
+export declare const rules: {
+    'order-properties': {
+        create(context: import("./createRule").PackageJsonRuleContext): import("jsonc-eslint-parser").RuleListener;
+        meta: import("eslint").Rule.RuleMetaData;
+    };
+    'sort-collections': {
+        create(context: import("./createRule").PackageJsonRuleContext): import("jsonc-eslint-parser").RuleListener;
+        meta: import("eslint").Rule.RuleMetaData;
+    };
+    'valid-local-dependency': {
+        create(context: import("./createRule").PackageJsonRuleContext): import("jsonc-eslint-parser").RuleListener;
+        meta: import("eslint").Rule.RuleMetaData;
+    };
+    'valid-package-def': {
+        create(context: import("./createRule").PackageJsonRuleContext): import("jsonc-eslint-parser").RuleListener;
+        meta: import("eslint").Rule.RuleMetaData;
+    };
+};
+export declare const configs: {
+    recommended: {
+        rules: {
+            'order-properties': {
+                create(context: import("./createRule").PackageJsonRuleContext): import("jsonc-eslint-parser").RuleListener;
+                meta: import("eslint").Rule.RuleMetaData;
+            };
+            'sort-collections': {
+                create(context: import("./createRule").PackageJsonRuleContext): import("jsonc-eslint-parser").RuleListener;
+                meta: import("eslint").Rule.RuleMetaData;
+            };
+            'valid-local-dependency': {
+                create(context: import("./createRule").PackageJsonRuleContext): import("jsonc-eslint-parser").RuleListener;
+                meta: import("eslint").Rule.RuleMetaData;
+            };
+            'valid-package-def': {
+                create(context: import("./createRule").PackageJsonRuleContext): import("jsonc-eslint-parser").RuleListener;
+                meta: import("eslint").Rule.RuleMetaData;
+            };
+        };
+    };
+};
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":""}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,KAAK;;;;;;;;;;;;;;;;;CAKjB,CAAC;AAEF,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;CAInB,CAAC"}

package/lib/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configs = exports.rules = void 0;
+const order_properties_1 = __importDefault(require("./rules/order-properties"));
+const sort_collections_1 = __importDefault(require("./rules/sort-collections"));
+const valid_local_dependency_1 = __importDefault(require("./rules/valid-local-dependency"));
+const valid_package_def_1 = __importDefault(require("./rules/valid-package-def"));
+exports.rules = {
+    'order-properties': order_properties_1.default,
+    'sort-collections': sort_collections_1.default,
+    'valid-local-dependency': valid_local_dependency_1.default,
+    'valid-package-def': valid_package_def_1.default
+};
+exports.configs = {
+    recommended: {
+        rules: exports.rules
+    }
+};

package/lib/rules/order-properties.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"order-properties.d.ts","sourceRoot":"","sources":["../../src/rules/order-properties.ts"],"names":[],"mappings":";;;;AAmCA,wBA0EG"}
+{"version":3,"file":"order-properties.d.ts","sourceRoot":"","sources":["../../src/rules/order-properties.ts"],"names":[],"mappings":";;;;AAmCA,wBAsFG"}

package/lib/rules/order-properties.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const sort_package_json_1 = __importDefault(require("sort-package-json"));
+const createRule_js_1 = require("../createRule.js");
+const standardOrderLegacy = [
+    'name',
+    'version',
+    'private',
+    'publishConfig',
+    'description',
+    'main',
+    'exports',
+    'browser',
+    'files',
+    'bin',
+    'directories',
+    'man',
+    'scripts',
+    'repository',
+    'keywords',
+    'author',
+    'license',
+    'bugs',
+    'homepage',
+    'config',
+    'dependencies',
+    'devDependencies',
+    'peerDependencies',
+    'optionalDependencies',
+    'bundledDependencies',
+    'engines',
+    'os',
+    'cpu'
+];
+exports.default = (0, createRule_js_1.createRule)({
+    meta: {
+        docs: {
+            description: 'Package properties must be declared in standard order',
+            category: 'Best Practices',
+            recommended: true
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'object',
+                properties: {
+                    order: {
+                        anyOf: [
+                            {
+                                type: ['string'],
+                                enum: ['legacy', 'sort-package-json']
+                            },
+                            {
+                                type: ['array'],
+                                items: {
+                                    type: ['string']
+                                }
+                            }
+                        ]
+                    }
+                }
+            }
+        ]
+    },
+    create(context) {
+        return {
+            'Program:exit'() {
+                const { ast, text } = context.sourceCode;
+                const options = context.options[0] || { order: 'legacy' };
+                const requiredOrder = options.order === 'legacy'
+                    ? standardOrderLegacy
+                    : options.order;
+                const orderedSource = (0, sort_package_json_1.default)(JSON.parse(text), requiredOrder === 'sort-package-json'
+                    ? undefined
+                    : {
+                        sortOrder: requiredOrder
+                    });
+                const orderedKeys = Object.keys(orderedSource);
+                const { properties } = ast.body[0].expression;
+                // console.log({ orderedSource });
+                for (let i = 0; i < properties.length; i += 1) {
+                    // console.log(
+                    //     properties.map(p => p.value),
+                    //     'vs',
+                    //     orderedKeys
+                    // );
+                    if (properties[i].value !== orderedKeys[i]) {
+                        // console.log(
+                        //     'JOSH SAYS HI',
+                        //     properties[i].value.value,
+                        //     orderedKeys[i]
+                        // );
+                        context.report({
+                            node: context.sourceCode.ast,
+                            message: 'Package top-level properties are not ordered in the npm standard way. Run the ESLint auto-fixer to correct.',
+                            fix(fixer) {
+                                return fixer.replaceText(context.sourceCode.ast, JSON.stringify(orderedSource, null, 2) +
+                                    `\n`);
+                            }
+                        });
+                    }
+                    break;
+                }
+            }
+        };
+    }
+});

package/lib/rules/sort-collections.js

@@ -0,0 +1,66 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const createRule_js_1 = require("../createRule.js");
+const defaultCollections = [
+    'scripts',
+    'devDependencies',
+    'dependencies',
+    'peerDependencies',
+    'config'
+];
+exports.default = (0, createRule_js_1.createRule)({
+    meta: {
+        docs: {
+            description: 'Dependencies, scripts, and configuration values must be declared in alphabetical order.',
+            category: 'Best Practices',
+            recommended: true
+        },
+        fixable: 'code',
+        schema: [
+            {
+                type: 'array',
+                items: {
+                    type: 'string'
+                }
+            }
+        ]
+    },
+    create(context) {
+        const toSort = context.options[0] || defaultCollections;
+        return {
+            'JSONProperty:exit'(node) {
+                const { key, value } = node;
+                const collection = value;
+                if (collection.type === 'JSONObjectExpression' &&
+                    toSort.includes(key.value)) {
+                    const currentOrder = collection.properties;
+                    const desiredOrder = currentOrder
+                        .slice()
+                        .sort((a, b) => a.key.value >
+                        b.key.value
+                        ? 1
+                        : -1);
+                    if (currentOrder.some((property, i) => desiredOrder[i] !== property)) {
+                        context.report({
+                            node: node,
+                            loc: collection.loc,
+                            message: 'Package {{ key }} are not alphabetized',
+                            data: {
+                                key: key.value
+                            },
+                            fix(fixer) {
+                                return fixer.replaceText(collection, JSON.stringify(desiredOrder.reduce((out, property) => {
+                                    out[property.key.value] = JSON.parse(context.sourceCode.getText(property.value));
+                                    return out;
+                                }, {}), null, 2)
+                                    .split('\n')
+                                    .join('\n  ') // nest indents
+                                );
+                            }
+                        });
+                    }
+                }
+            }
+        };
+    }
+});

package/lib/rules/valid-local-dependency.js

@@ -0,0 +1,57 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const path_1 = __importDefault(require("path"));
+const createRule_js_1 = require("../createRule.js");
+//------------------------------------------------------------------------------
+// Rule Definition
+//------------------------------------------------------------------------------
+exports.default = (0, createRule_js_1.createRule)({
+    meta: {
+        docs: {
+            description: 'Checks existence of local dependencies in the package.json',
+            category: 'Best Practices',
+            recommended: true
+        }
+    },
+    create: function (context) {
+        return {
+            'Program:exit'() {
+                const original = JSON.parse(context.sourceCode.text);
+                const { dependencies, peerDependencies, devDependencies } = original;
+                const depObjs = [
+                    Object.entries(dependencies || {}),
+                    Object.entries(peerDependencies || {}),
+                    Object.entries(devDependencies || {})
+                ];
+                depObjs.forEach(obj => obj.forEach(([key, value]) => {
+                    const response = (localPath) => {
+                        const filePath = path_1.default.join(context.filename.replace(/package\.json/g, '/'), value.replace(new RegExp(localPath, 'g'), ''), '/package.json');
+                        try {
+                            if (!require.resolve(filePath)) {
+                                context.report({
+                                    node: context.sourceCode.ast,
+                                    message: `The package ${key} does not exist given the specified path: ${value}.`
+                                });
+                            }
+                        }
+                        catch (e) {
+                            context.report({
+                                node: context.sourceCode.ast,
+                                message: `The package ${key} does not exist given the specified path: ${value}.`
+                            });
+                        }
+                    };
+                    if (value.startsWith('link:')) {
+                        response('link:');
+                    }
+                    if (value.startsWith('file:')) {
+                        response('file:');
+                    }
+                }));
+            }
+        };
+    }
+});

package/lib/rules/valid-package-def.js

@@ -0,0 +1,34 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const package_json_validator_1 = require("package-json-validator");
+const createRule_js_1 = require("../createRule.js");
+// package-json-validator does not correctly recognize shorthand for repositories and alternate dependency statements, so we discard those values.
+// it also enforces a stricter code for NPM than is really appropriate,
+// so we disable some other errors here.
+const unusedErrorPatterns = [
+    /^Url not valid/i,
+    /^Invalid version range for .+?: file:/i,
+    /^author field should have name/i
+];
+const isUsableError = (errorText) => unusedErrorPatterns.every(pattern => !pattern.test(errorText));
+exports.default = (0, createRule_js_1.createRule)({
+    meta: {
+        docs: {
+            description: 'Enforce that package.json has all properties required by NPM spec',
+            category: 'Best Practices',
+            recommended: true
+        }
+    },
+    create: function (context) {
+        return {
+            'Program:exit'() {
+                const validation = package_json_validator_1.PJV.validate(context.sourceCode.text);
+                validation.errors?.filter(isUsableError).forEach(message => message &&
+                    context.report({
+                        node: context.sourceCode.ast,
+                        message
+                    }));
+            }
+        };
+    }
+});

package/lib/tests/rules/order-properties.test.js

@@ -8,7 +8,6 @@ const ruleTester_1 = require("./ruleTester");
 ruleTester_1.ruleTester.run('order-properties', order_properties_1.default, {
     invalid: [
         {
-            only: true,
             code: `{
     "name": "invalid-top-level-property-order",
     "scripts": {
@@ -45,7 +44,6 @@ ruleTester_1.ruleTester.run('order-properties', order_properties_1.default, {
 `
         },
         {
-            only: true,
             code: `{
     "name": "invalid-top-level-property-order",
     "scripts": {
@@ -83,7 +81,6 @@ ruleTester_1.ruleTester.run('order-properties', order_properties_1.default, {
 `
         },
         {
-            only: true,
             code: `{
     "name": "invalid-top-level-property-order",
     "scripts": {
@@ -121,7 +118,6 @@ ruleTester_1.ruleTester.run('order-properties', order_properties_1.default, {
 `
         },
         {
-            only: true,
             code: `{
     "name": "invalid-top-level-property-order",
     "scripts": {
@@ -160,8 +156,7 @@ ruleTester_1.ruleTester.run('order-properties', order_properties_1.default, {
         }
     ],
     valid: [
-        {
-            code: `{
+        `{
       "name": "treat-yo-self",
       "version": "1.1.1",
       "description": "Once a year.",
@@ -170,10 +165,7 @@ ruleTester_1.ruleTester.run('order-properties', order_properties_1.default, {
         "master"
       ]
     }`,
-            filename: 'package.json'
-        },
-        {
-            code: `{
+        `{
       "name": "treat-yo-self",
       "version": "0.1.0",
       "private": true,
@@ -183,8 +175,7 @@ ruleTester_1.ruleTester.run('order-properties', order_properties_1.default, {
         "master"
       ]
     }
-    `
-        },
+    `,
         {
             code: `{
       "version": "1.1.1",

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "eslint-plugin-package-json",
-    "version": "0.3.1",
+    "version": "0.3.2",
     "description": "Rules for valid, consistent, and readable package.json files",
     "keywords": [
         "eslint",
@@ -21,8 +21,10 @@
     },
     "scripts": {
         "lint": "eslint",
+        "lint:eslint-docs": "npm run update:eslint-docs -- --check",
         "test": "vitest",
         "tsc": "tsc",
+        "update:eslint-docs": "eslint-doc-generator",
         "format": "prettier --ignore-path .gitignore --write \"**/*.{js,css,md}\""
     },
     "devDependencies": {
@@ -32,6 +34,7 @@
         "@types/package-json-validator": "^0.6.0",
         "console-fail-test": "^0.2.3",
         "eslint": "^8.49.0",
+        "eslint-doc-generator": "^1.5.4",
         "jsonc-eslint-parser": "^2.4.0",
         "prettier": "^1.18.2",
         "typescript": "^5.2.2",

package/src/index.ts

@@ -1,19 +1,17 @@
-'use strict';
-
 import orderProperties from './rules/order-properties';
 import sortCollections from './rules/sort-collections';
 import validLocalDependency from './rules/valid-local-dependency';
 import validPackageDef from './rules/valid-package-def';
 
-module.exports = {
-    configs: {
-        recommended: {
-            rules: {
-                'order-properties': orderProperties,
-                'sort-collections': sortCollections,
-                'valid-local-dependency': validLocalDependency,
-                'valid-package-def': validPackageDef
-            }
-        }
+export const rules = {
+    'order-properties': orderProperties,
+    'sort-collections': sortCollections,
+    'valid-local-dependency': validLocalDependency,
+    'valid-package-def': validPackageDef
+};
+
+export const configs = {
+    recommended: {
+        rules
     }
 };