exadev-eslint-config 2.14.0 → 2.15.0

package/README.md

@@ -166,7 +166,23 @@ Every JSON file (`**/*.json`, excluding `**/tsconfig*.json`, `**/turbo.json`, an
 
 The plugin's own whitespace-collapsing rule (`no-insignificant-whitespace`, which reformats a document to a single compacted line) is deliberately not part of `configs.recommended` and is not enabled here either -- it stays available for a consumer to opt into directly for their own genuine canonicalization pass.
 
-`**/tsconfig*.json` and `**/turbo.json` are excluded because they genuinely carry comments (TypeScript and turbo both accept them), which `@eslint/json`'s `json/json` language -- what this plugin's recommended config hard-codes -- has no concept of and fails to parse. `**/package.json` is excluded because its key order is a distinct, separately-optional concern (syncpack-style field-priority pinning, not RFC 8785's plain alphabetical order); a project wanting that instead reaches for `eslint-plugin-json-canonical` directly on its own terms, not through this package.
+`**/tsconfig*.json` and `**/turbo.json` are excluded because they genuinely carry comments (TypeScript and turbo both accept them), which `@eslint/json`'s `json/json` language -- what this plugin's recommended config hard-codes -- has no concept of and fails to parse. `**/package.json`'s own key order is excluded from this bundle specifically (its number-format/string-escaping rules still apply) since ordering is the separate, syncpack-aware concern the next section covers.
+
+## Optional package.json key ordering
+
+`exadevConfig({ packageJsonKeyOrder: true })` enables `exadev/package-json-key-order` for `**/package.json`, requiring the same key order [`syncpack format`](https://syncpack.dev/command/format) would produce -- `sortFirst` fields (`name`, `description`, `version`, `author` by default) pinned to the top in that exact order, then every other top-level key alphabetically; and, inside each `sortAz`-listed field's own object or array value (`dependencies`, `devDependencies`, `scripts`, `keywords`, and the rest of syncpack's own default list), its members/elements sorted the same way. Confirmed directly against real `syncpack@15` output, not assumed from its docs -- see this rule's own source comment for the exact reverse-engineering method (a symbol-before-digit-before-letter, case-insensitive comparison syncpack's docs don't specify precisely enough to derive from prose alone).
+
+This exists for a project that wants real `package.json` canonicalization without installing syncpack, and so a project that already has syncpack never sees the two fight: `eslint --fix` and `syncpack format` converge on the identical output.
+
+| Value | `options.packageJsonKeyOrder` |
+| --- | --- |
+| `true` | Force on -- throws if `@eslint/json` isn't resolvable |
+| `false` | Force off -- always `[]`, no resolution attempted |
+| `undefined` / omitted | Auto-detect (the default): on unless the project already has a syncpack config (a `.syncpackrc*`/`syncpack.config.*` file, or a `"syncpack"` key in its own `package.json`), since syncpack already produces this exact order for free |
+
+Like React/Next.js support, this needs its own optional peer resolvable -- `pnpm add -D @eslint/json` -- and, unlike them, also needs its `json/json` language registered for the file (this option's own config block does that for you; nothing extra to wire up).
+
+Bundled into `exadevConfig()`'s default output the same way React/Next.js auto-detection is (see the table above) -- `packageJsonKeyOrder: true`/`false` only forces the tri-state explicitly, it isn't the only way to reach it. Not part of `plugin.configs.recommended`, and not available as a `plugin.configs.packageJsonKeyOrder` explicit-tier config the way `.react`/`.nextjs` are, since wiring it through `plugin.configs` would need `plugin.ts` and this option's own config builder to import each other.
 
 ## Rules
 
@@ -190,6 +206,7 @@ The plugin's own whitespace-collapsing rule (`no-insignificant-whitespace`, whic
 | `no-enum-number-widening` | | A bare (non-literal) `number` is accepted anywhere a numeric enum is expected, without checking it is actually one of the enum's members -- only a numeric *literal* gets range-checked by `tsc`. No autofix: the only provably safe fix is a genuine runtime membership check against the enum's own values, which is a behavioural choice a mechanical fix cannot responsibly make. Requires type information -- only in the default (type-checked) export, not `plugin.configs.recommended`. |
 | `no-enum-reverse-lookup-widening` | suggestion | Indexing a numeric enum's reverse mapping (`Direction[n]`) with a bare (non-literal) `number`, or with a different enum's member, types as plain `string` for any index, including one outside the enum's actual members, where it genuinely returns `undefined` at runtime -- `tsc` does not range-check even a numeric literal index here. When the indexed expression is the init of a variable with an explicit `: string` annotation, a suggestion widens it to `: string \| undefined`, forcing later uses as a bare `string` to surface as real compile errors; every other syntactic position gets a plain report with no fix, and no case gets a full `--fix` autofix. Requires type information -- only in the default (type-checked) export, not `plugin.configs.recommended`. |
 | `prefer-numeric-sort-compare` | suggestion | A deliberately narrow addition alongside `@typescript-eslint/require-array-sort-compare` (which already flags any bare `.sort()`/`.toSorted()` except on a plain string array, with no fix): when the array's element type is definitively `number`, a suggestion offers an ascending compare function (`(a, b) => a - b`), since the default comparator sorts lexicographically (`[1, 2, 10].sort()` becomes `[1, 10, 2]`). Not a full autofix -- descending order is a real, if less common, alternative intent. Requires type information -- only in the default (type-checked) export, not `plugin.configs.recommended`, since it needs the checker to confirm the array's element type. |
+| `package-json-key-order` | ✓ | Requires `package.json`'s keys to be ordered the same way `syncpack format` would order them. See [Optional package.json key ordering](#optional-package-json-key-ordering) -- opt-in via `exadevConfig({ packageJsonKeyOrder: true })`, not part of `recommended`/`barrel`. A JSON-language rule (`@eslint/json`'s `json/json`), not a TSESLint one -- needs no type information and doesn't apply to any `.ts`/`.js` file. |
 
 ## Barrel policy
 

package/dist/index.cjs

@@ -31,15 +31,16 @@ eslint_plugin_tsdoc = __toESM(eslint_plugin_tsdoc, 1);
 let eslint_plugin_json_canonical = require("eslint-plugin-json-canonical");
 eslint_plugin_json_canonical = __toESM(eslint_plugin_json_canonical, 1);
 let node_module = require("node:module");
-let _eslint_js = require("@eslint/js");
-_eslint_js = __toESM(_eslint_js, 1);
-let typescript_eslint = require("typescript-eslint");
-typescript_eslint = __toESM(typescript_eslint, 1);
+let node_fs = require("node:fs");
 let node_path = require("node:path");
 let _typescript_eslint_utils = require("@typescript-eslint/utils");
 let typescript = require("typescript");
 typescript = __toESM(typescript, 1);
 let ts_api_utils = require("ts-api-utils");
+let _eslint_js = require("@eslint/js");
+_eslint_js = __toESM(_eslint_js, 1);
+let typescript_eslint = require("typescript-eslint");
+typescript_eslint = __toESM(typescript_eslint, 1);
 //#region src/jsdoc.ts
 const JS_TS_FILE_PATTERNS$1 = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
 const jsdocConfig = eslint_plugin_jsdoc.default.configs["flat/recommended-tsdoc-error"];
@@ -101,16 +102,16 @@ function tryRequire(specifier, requireFn = nodeRequire) {
 		return;
 	}
 }
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
 function isFlatConfig$1(value) {
-	return isRecord(value);
+	return isRecord$1(value);
 }
 function normalizeLegacyParserOptions(record) {
 	if (!("parserOptions" in record)) return record;
 	const { parserOptions, languageOptions, ...rest } = record;
-	const existingLanguageOptions = isRecord(languageOptions) ? languageOptions : {};
+	const existingLanguageOptions = isRecord$1(languageOptions) ? languageOptions : {};
 	return {
 		...rest,
 		languageOptions: {
@@ -122,10 +123,10 @@ function normalizeLegacyParserOptions(record) {
 function readFlatConfig(module, path) {
 	let current = module;
 	for (const key of path) {
-		if (!isRecord(current)) return void 0;
+		if (!isRecord$1(current)) return void 0;
 		current = current[key];
 	}
-	if (!isRecord(current)) return void 0;
+	if (!isRecord$1(current)) return void 0;
 	const normalized = normalizeLegacyParserOptions(current);
 	return isFlatConfig$1(normalized) ? normalized : void 0;
 }
@@ -139,6 +140,9 @@ function buildNextjsConfig(options = {}) {
 	return nextConfig === void 0 ? [] : [nextConfig];
 }
 //#endregion
+//#region package.json
+var version = "2.15.0";
+//#endregion
 //#region src/react.ts
 const JSX_FILE_PATTERNS = ["**/*.jsx", "**/*.tsx"];
 const INSTALL_COMMAND = "pnpm add -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y";
@@ -176,9 +180,6 @@ function buildReactConfig(options = {}) {
 	}));
 }
 //#endregion
-//#region package.json
-var version = "2.14.0";
-//#endregion
 //#region src/rules/barrel-helpers.ts
 const INDEX_BASENAME$1 = /^index\.[cm]?[tj]sx?$/;
 function basenameOf(filename) {
@@ -1234,6 +1235,215 @@ const noSideEffectsInIndex = {
 	}
 };
 //#endregion
+//#region src/rules/package-json-key-order.ts
+const DEFAULT_SORT_FIRST = [
+	"name",
+	"description",
+	"version",
+	"author"
+];
+const DEFAULT_SORT_AZ = [
+	"bin",
+	"contributors",
+	"dependencies",
+	"devDependencies",
+	"keywords",
+	"peerDependencies",
+	"resolutions",
+	"scripts"
+];
+function categorize(char) {
+	if (char >= "0" && char <= "9") return 1;
+	if (/[a-z]/iu.test(char)) return 2;
+	return 0;
+}
+/** Case-insensitive, symbol-before-digit-before-letter comparison matching real `syncpack format` output. Returns a negative number if `a` sorts before `b`, positive if after, zero if equal. */
+function compareSyncpackKey(a, b) {
+	const length = Math.min(a.length, b.length);
+	for (let index = 0; index < length; index += 1) {
+		const charA = a[index] ?? "";
+		const charB = b[index] ?? "";
+		const categoryA = categorize(charA);
+		const categoryB = categorize(charB);
+		if (categoryA !== categoryB) return categoryA - categoryB;
+		const foldedA = categoryA === 2 ? charA.toLowerCase() : charA;
+		const foldedB = categoryB === 2 ? charB.toLowerCase() : charB;
+		if (foldedA !== foldedB) return foldedA < foldedB ? -1 : 1;
+	}
+	return a.length - b.length;
+}
+/**
+* The pure decision for an adjacent pair of top-level keys, independent of ESLint/momoa: given syncpack's own `sortFirst` list, is `curr` allowed to immediately follow `prev`? A pinned key (present in `sortFirst`) must appear in exactly `sortFirst`'s own order; every other key sorts after every pinned key, and among themselves by `compareSyncpackKey`. Kept separate from `create()` below so it can be unit-tested directly, matching the same pattern `no-uphill-dependency`'s `checkDependencies` in the monorepo-template uses.
+*/
+function isValidTopLevelOrder(prev, curr, sortFirst) {
+	const prevIndex = sortFirst.indexOf(prev);
+	const currIndex = sortFirst.indexOf(curr);
+	if (prevIndex !== -1 && currIndex !== -1) return prevIndex < currIndex;
+	if (prevIndex !== -1) return true;
+	if (currIndex !== -1) return false;
+	return compareSyncpackKey(prev, curr) <= 0;
+}
+/** The pure decision for an adjacent pair of keys/elements inside a `sortAz`-listed field's own object or array value: plain `compareSyncpackKey` order, no pinning. */
+function isValidSortAzOrder(prev, curr) {
+	return compareSyncpackKey(prev, curr) <= 0;
+}
+/**
+* The target permutation for a whole container's own keys, given a comparator over adjacent pairs (either `isValidTopLevelOrder`-shaped or `isValidSortAzOrder`-shaped). Returns, for each output position, the ORIGINAL index of the key that belongs there -- e.g. `[2, 0, 1]` means the key currently at index 2 comes first. A stable sort (ties keep their original relative order), matching real syncpack output for keys that compare equal (see `compareSyncpackKey`'s own case-insensitive-letter test case).
+*
+* Reordering by computing this full permutation once, rather than reporting and fixing one out-of-order adjacent pair at a time (the technique `@eslint/json`'s own `sort-keys` rule uses), is deliberate: an adjacent-swap fixer only makes one pass of bubble-sort-style progress per lint pass, and a realistically scrambled `package.json` (many top-level keys all needing to move several positions, several nested objects also needing sorting) was confirmed directly to need up to 11 fix passes to fully converge -- one more than ESLint's own `Linter#verifyAndFix` will ever run (`MAX_AUTOFIX_PASSES` is 10), meaning a single real `eslint --fix` invocation could leave such a file only partially reordered. Computing the whole target order up front and replacing every affected key's position in one combined fix converges in a single pass regardless of how scrambled the input is.
+*/
+function computeOrderPermutation(keys, isValidOrder) {
+	return keys.map((_, index) => index).map((index) => ({
+		key: keys[index] ?? "",
+		index
+	})).sort((a, b) => {
+		if (isValidOrder(a.key, b.key) && isValidOrder(b.key, a.key)) return a.index - b.index;
+		return isValidOrder(a.key, b.key) ? -1 : 1;
+	}).map((entry) => entry.index);
+}
+function isIdentityPermutation(permutation) {
+	return permutation.every((originalIndex, position) => originalIndex === position);
+}
+function isStringNode(node) {
+	return node.type === "String";
+}
+function getMemberKeyName(member) {
+	return member.name.type === "String" ? member.name.value : void 0;
+}
+function hasRange(node) {
+	return node.range !== void 0;
+}
+const commentTypes = /* @__PURE__ */ new Set(["LineComment", "BlockComment"]);
+/**
+* Enforces the same `package.json` key order `syncpack format` would produce: `sortFirst` fields pinned to the top in that exact order, then every other top-level key alphabetically; and, inside each `sortAz`-listed field's own object or array value, its members/elements sorted the same way (no pinning there -- `sortFirst` only ever applies at the top level).
+*
+* This exists so a project using `@exadev/eslint-config` without syncpack still gets real `package.json` canonicalization, and so a project using both never sees them fight: `eslint --fix` and `syncpack format` converge on the identical output, confirmed directly against real `syncpack@15` output rather than assumed from its docs (see `compareSyncpackKey`'s own comment). Deliberately narrower than `@eslint/json`'s own `sort-keys` rule, which only supports a single alphabetical order for every key with no field-specific pinning -- not a fit for syncpack's own two-tier scheme.
+*
+* Not part of `plugin.configs.recommended`: opt-in, the same tri-state shape as `react`/`nextjs` (see `docs.md`'s own usage example), since a project without syncpack needs to choose this deliberately, and a project with syncpack needs to confirm the two tools agree before turning it on.
+*/
+const packageJsonKeyOrder = {
+	meta: {
+		type: "layout",
+		fixable: "code",
+		languages: ["json/json", "json/jsonc"],
+		docs: {
+			recommended: false,
+			description: "Require package.json keys to be ordered the same way `syncpack format` would order them.",
+			url: "https://github.com/ExaDev/eslint-config/blob/main/src/rules/package-json-key-order.ts"
+		},
+		schema: [{
+			type: "object",
+			properties: {
+				sortFirst: {
+					type: "array",
+					items: { type: "string" }
+				},
+				sortAz: {
+					type: "array",
+					items: { type: "string" }
+				}
+			},
+			additionalProperties: false
+		}],
+		defaultOptions: [{}],
+		messages: { outOfOrder: "This key order does not match the order \"syncpack format\" would produce: \"{{curr}}\" should come before \"{{prev}}\" here." }
+	},
+	create(context) {
+		const [options] = context.options;
+		const sortFirst = options.sortFirst ?? DEFAULT_SORT_FIRST;
+		const sortAz = new Set(options.sortAz ?? DEFAULT_SORT_AZ);
+		const { sourceCode } = context;
+		function hasAdjacentComment(node) {
+			const before = sourceCode.getTokenBefore(node, { includeComments: true });
+			let after = sourceCode.getTokenAfter(node, { includeComments: true });
+			if (after?.type === "Comma") after = sourceCode.getTokenAfter(after, { includeComments: true });
+			return before !== null && commentTypes.has(before.type) || after !== null && commentTypes.has(after.type);
+		}
+		function buildReorderedText(nodes, permutation) {
+			const separators = nodes.slice(0, -1).map((node, index) => {
+				const next = nodes[index + 1];
+				return hasRange(node) && next !== void 0 && hasRange(next) ? sourceCode.text.slice(node.range[1], next.range[0]) : "";
+			});
+			return permutation.reduce((result, originalIndex, position) => {
+				const text = sourceCode.getText(nodes[originalIndex]);
+				return position === 0 ? text : `${result}${separators[position - 1] ?? ""}${text}`;
+			}, "");
+		}
+		function getNodeRanges(nodes) {
+			const ranges = [];
+			for (const node of nodes) {
+				if (!hasRange(node)) return void 0;
+				ranges.push(node.range);
+			}
+			return ranges;
+		}
+		function reportWholeContainerReorder(nodes, keys, isValidOrder, reportLoc) {
+			const permutation = computeOrderPermutation(keys, isValidOrder);
+			if (isIdentityPermutation(permutation)) return;
+			const firstNode = nodes[0];
+			const lastNode = nodes[nodes.length - 1];
+			if (firstNode === void 0 || lastNode === void 0) return;
+			let violationIndex = 1;
+			for (let index = 1; index < keys.length; index += 1) if (!isValidOrder(keys[index - 1] ?? "", keys[index] ?? "")) {
+				violationIndex = index;
+				break;
+			}
+			context.report({
+				loc: reportLoc(nodes[violationIndex] ?? firstNode),
+				messageId: "outOfOrder",
+				data: {
+					curr: keys[violationIndex] ?? "",
+					prev: keys[violationIndex - 1] ?? ""
+				},
+				fix(fixer) {
+					const ranges = getNodeRanges(nodes);
+					if (ranges === void 0 || nodes.some((node) => hasAdjacentComment(node))) return null;
+					const firstRange = ranges[0];
+					const lastRange = ranges[ranges.length - 1];
+					if (firstRange === void 0 || lastRange === void 0) return null;
+					const rewritten = buildReorderedText(nodes, permutation);
+					return fixer.replaceTextRange([firstRange[0], lastRange[1]], rewritten);
+				}
+			});
+		}
+		function checkMembers(members, isValidOrder) {
+			const keys = [];
+			for (const member of members) {
+				const key = getMemberKeyName(member);
+				if (key === void 0) return;
+				keys.push(key);
+			}
+			reportWholeContainerReorder(members, keys, isValidOrder, (member) => member.name.loc.start);
+		}
+		function checkElements(elements) {
+			const stringValues = [];
+			for (const element of elements) {
+				if (!isStringNode(element.value)) return;
+				stringValues.push(element.value);
+			}
+			reportWholeContainerReorder(stringValues, stringValues.map((value) => value.value), isValidSortAzOrder, (value) => value.loc.start);
+		}
+		return {
+			Object(node, parent) {
+				if (parent === void 0) return;
+				if (parent.type === "Document") {
+					checkMembers(node.members, (prev, curr) => isValidTopLevelOrder(prev, curr, sortFirst));
+					return;
+				}
+				if (parent.type === "Member") {
+					const key = getMemberKeyName(parent);
+					if (key !== void 0 && sortAz.has(key)) checkMembers(node.members, isValidSortAzOrder);
+				}
+			},
+			Array(node, parent) {
+				if (parent?.type !== "Member") return;
+				const key = getMemberKeyName(parent);
+				if (key !== void 0 && sortAz.has(key)) checkElements(node.elements);
+			}
+		};
+	}
+};
+//#endregion
 //#region src/rules/prefer-numeric-sort-compare.ts
 const createRule$2 = _typescript_eslint_utils.ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 const SORT_METHOD_NAMES = /* @__PURE__ */ new Set(["sort", "toSorted"]);
@@ -1456,6 +1666,7 @@ const plugin = {
 		"no-pointless-reassignment": noPointlessReassignment,
 		"no-set-instanceof-mutation": noSetInstanceofMutation,
 		"no-side-effects-in-index": noSideEffectsInIndex,
+		"package-json-key-order": packageJsonKeyOrder,
 		"prefer-numeric-sort-compare": preferNumericSortCompare,
 		"prefer-readonly-array-param": preferReadonlyArrayParam,
 		"prefer-readonly-object-param": preferReadonlyObjectParam
@@ -1489,6 +1700,69 @@ const plugin = {
 	}
 };
 //#endregion
+//#region src/package-json-key-order.ts
+const SYNCPACK_CONFIG_FILENAMES = [
+	".syncpackrc",
+	".syncpackrc.json",
+	".syncpackrc.yaml",
+	".syncpackrc.yml",
+	".syncpackrc.js",
+	".syncpackrc.cjs",
+	".syncpackrc.mjs",
+	"syncpack.config.js",
+	"syncpack.config.cjs",
+	"syncpack.config.mjs",
+	"syncpack.config.ts"
+];
+function packageJsonHasSyncpackKey(cwd) {
+	try {
+		const raw = JSON.parse((0, node_fs.readFileSync)((0, node_path.join)(cwd, "package.json"), "utf8"));
+		return typeof raw === "object" && raw !== null && "syncpack" in raw;
+	} catch {
+		return false;
+	}
+}
+/** Auto-detection signal for the `enabled: undefined` case: does this project already have syncpack configured? Mirrors the role `tryRequire`'s peer-package resolution plays for `react.ts`/`nextjs.ts`, but for a tool detected by config presence rather than by an installed package, since syncpack's own output is what this rule is emulating, not a peer this rule depends on. */
+function hasSyncpackConfig(cwd) {
+	return SYNCPACK_CONFIG_FILENAMES.some((filename) => (0, node_fs.existsSync)((0, node_path.join)(cwd, filename))) || packageJsonHasSyncpackKey(cwd);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isJsonLanguagePlugin(value) {
+	if (!isRecord(value)) return false;
+	const languages = value["languages"];
+	return isRecord(languages) && "json" in languages;
+}
+function resolveJsonPlugin(value) {
+	if (isRecord(value) && isJsonLanguagePlugin(value["default"])) return value["default"];
+	return isJsonLanguagePlugin(value) ? value : void 0;
+}
+const JSON_PLUGIN_INSTALL_COMMAND = "pnpm add -D @eslint/json";
+function buildPackageJsonKeyOrderConfig(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	if (options.enabled === false) return [];
+	if (options.enabled === void 0 && hasSyncpackConfig(cwd)) return [];
+	const jsonPlugin = resolveJsonPlugin(tryRequire("@eslint/json", options.requireFn));
+	if (jsonPlugin === void 0) {
+		if (options.enabled === true) throw new Error(`@exadev/eslint-config: package.json key ordering was explicitly requested but '@eslint/json' could not be resolved. Install it with: ${JSON_PLUGIN_INSTALL_COMMAND}`);
+		return [];
+	}
+	const ruleOptions = {
+		...options.sortFirst !== void 0 && { sortFirst: options.sortFirst },
+		...options.sortAz !== void 0 && { sortAz: options.sortAz }
+	};
+	return [{
+		files: ["**/package.json"],
+		language: "json/json",
+		plugins: {
+			exadev: plugin,
+			json: jsonPlugin
+		},
+		rules: { "exadev/package-json-key-order": ["error", ruleOptions] }
+	}];
+}
+//#endregion
 //#region src/recommended-type-checked.ts
 const TEST_FILE_PATTERNS = "**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
 const JS_TS_FILE_PATTERNS = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
@@ -1583,6 +1857,7 @@ function exadevConfig(options = {}, ...userConfigs) {
 		...jsonCanonicalConfig,
 		...buildReactConfig({ enabled: options.react }),
 		...buildNextjsConfig({ enabled: options.nextjs }),
+		...buildPackageJsonKeyOrderConfig({ enabled: options.packageJsonKeyOrder }),
 		...userConfigs
 	]);
 }

package/dist/index.d.cts

@@ -7,6 +7,7 @@ type PublicConfigArray = Config[];
 interface ExadevConfigOptions {
   readonly react?: boolean;
   readonly nextjs?: boolean;
+  readonly packageJsonKeyOrder?: boolean;
 }
 declare function exadevConfig(options?: ExadevConfigOptions, ...userConfigs: readonly TSESLint.FlatConfig.Config[]): PublicConfigArray;
 declare const defaultConfig: PublicConfigArray;

package/dist/index.d.ts

@@ -7,6 +7,7 @@ type PublicConfigArray = Config[];
 interface ExadevConfigOptions {
   readonly react?: boolean;
   readonly nextjs?: boolean;
+  readonly packageJsonKeyOrder?: boolean;
 }
 declare function exadevConfig(options?: ExadevConfigOptions, ...userConfigs: readonly TSESLint.FlatConfig.Config[]): PublicConfigArray;
 declare const defaultConfig: PublicConfigArray;

package/dist/index.js

@@ -2,12 +2,13 @@ import jsdoc from "eslint-plugin-jsdoc";
 import tsdoc from "eslint-plugin-tsdoc";
 import jsonCanonical from "eslint-plugin-json-canonical";
 import { createRequire } from "node:module";
-import js from "@eslint/js";
-import tseslint from "typescript-eslint";
-import { posix } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
 import { AST_NODE_TYPES, ESLintUtils, TSESLint } from "@typescript-eslint/utils";
 import * as ts from "typescript";
 import { isPropertyReadonlyInType, isTypeReference } from "ts-api-utils";
+import js from "@eslint/js";
+import tseslint from "typescript-eslint";
 //#region src/jsdoc.ts
 const JS_TS_FILE_PATTERNS$1 = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
 const jsdocConfig = jsdoc.configs["flat/recommended-tsdoc-error"];
@@ -69,16 +70,16 @@ function tryRequire(specifier, requireFn = nodeRequire) {
 		return;
 	}
 }
-function isRecord(value) {
+function isRecord$1(value) {
 	return typeof value === "object" && value !== null;
 }
 function isFlatConfig$1(value) {
-	return isRecord(value);
+	return isRecord$1(value);
 }
 function normalizeLegacyParserOptions(record) {
 	if (!("parserOptions" in record)) return record;
 	const { parserOptions, languageOptions, ...rest } = record;
-	const existingLanguageOptions = isRecord(languageOptions) ? languageOptions : {};
+	const existingLanguageOptions = isRecord$1(languageOptions) ? languageOptions : {};
 	return {
 		...rest,
 		languageOptions: {
@@ -90,10 +91,10 @@ function normalizeLegacyParserOptions(record) {
 function readFlatConfig(module, path) {
 	let current = module;
 	for (const key of path) {
-		if (!isRecord(current)) return void 0;
+		if (!isRecord$1(current)) return void 0;
 		current = current[key];
 	}
-	if (!isRecord(current)) return void 0;
+	if (!isRecord$1(current)) return void 0;
 	const normalized = normalizeLegacyParserOptions(current);
 	return isFlatConfig$1(normalized) ? normalized : void 0;
 }
@@ -107,6 +108,9 @@ function buildNextjsConfig(options = {}) {
 	return nextConfig === void 0 ? [] : [nextConfig];
 }
 //#endregion
+//#region package.json
+var version = "2.15.0";
+//#endregion
 //#region src/react.ts
 const JSX_FILE_PATTERNS = ["**/*.jsx", "**/*.tsx"];
 const INSTALL_COMMAND = "pnpm add -D eslint-plugin-react eslint-plugin-react-hooks eslint-plugin-jsx-a11y";
@@ -144,9 +148,6 @@ function buildReactConfig(options = {}) {
 	}));
 }
 //#endregion
-//#region package.json
-var version = "2.14.0";
-//#endregion
 //#region src/rules/barrel-helpers.ts
 const INDEX_BASENAME$1 = /^index\.[cm]?[tj]sx?$/;
 function basenameOf(filename) {
@@ -1202,6 +1203,215 @@ const noSideEffectsInIndex = {
 	}
 };
 //#endregion
+//#region src/rules/package-json-key-order.ts
+const DEFAULT_SORT_FIRST = [
+	"name",
+	"description",
+	"version",
+	"author"
+];
+const DEFAULT_SORT_AZ = [
+	"bin",
+	"contributors",
+	"dependencies",
+	"devDependencies",
+	"keywords",
+	"peerDependencies",
+	"resolutions",
+	"scripts"
+];
+function categorize(char) {
+	if (char >= "0" && char <= "9") return 1;
+	if (/[a-z]/iu.test(char)) return 2;
+	return 0;
+}
+/** Case-insensitive, symbol-before-digit-before-letter comparison matching real `syncpack format` output. Returns a negative number if `a` sorts before `b`, positive if after, zero if equal. */
+function compareSyncpackKey(a, b) {
+	const length = Math.min(a.length, b.length);
+	for (let index = 0; index < length; index += 1) {
+		const charA = a[index] ?? "";
+		const charB = b[index] ?? "";
+		const categoryA = categorize(charA);
+		const categoryB = categorize(charB);
+		if (categoryA !== categoryB) return categoryA - categoryB;
+		const foldedA = categoryA === 2 ? charA.toLowerCase() : charA;
+		const foldedB = categoryB === 2 ? charB.toLowerCase() : charB;
+		if (foldedA !== foldedB) return foldedA < foldedB ? -1 : 1;
+	}
+	return a.length - b.length;
+}
+/**
+* The pure decision for an adjacent pair of top-level keys, independent of ESLint/momoa: given syncpack's own `sortFirst` list, is `curr` allowed to immediately follow `prev`? A pinned key (present in `sortFirst`) must appear in exactly `sortFirst`'s own order; every other key sorts after every pinned key, and among themselves by `compareSyncpackKey`. Kept separate from `create()` below so it can be unit-tested directly, matching the same pattern `no-uphill-dependency`'s `checkDependencies` in the monorepo-template uses.
+*/
+function isValidTopLevelOrder(prev, curr, sortFirst) {
+	const prevIndex = sortFirst.indexOf(prev);
+	const currIndex = sortFirst.indexOf(curr);
+	if (prevIndex !== -1 && currIndex !== -1) return prevIndex < currIndex;
+	if (prevIndex !== -1) return true;
+	if (currIndex !== -1) return false;
+	return compareSyncpackKey(prev, curr) <= 0;
+}
+/** The pure decision for an adjacent pair of keys/elements inside a `sortAz`-listed field's own object or array value: plain `compareSyncpackKey` order, no pinning. */
+function isValidSortAzOrder(prev, curr) {
+	return compareSyncpackKey(prev, curr) <= 0;
+}
+/**
+* The target permutation for a whole container's own keys, given a comparator over adjacent pairs (either `isValidTopLevelOrder`-shaped or `isValidSortAzOrder`-shaped). Returns, for each output position, the ORIGINAL index of the key that belongs there -- e.g. `[2, 0, 1]` means the key currently at index 2 comes first. A stable sort (ties keep their original relative order), matching real syncpack output for keys that compare equal (see `compareSyncpackKey`'s own case-insensitive-letter test case).
+*
+* Reordering by computing this full permutation once, rather than reporting and fixing one out-of-order adjacent pair at a time (the technique `@eslint/json`'s own `sort-keys` rule uses), is deliberate: an adjacent-swap fixer only makes one pass of bubble-sort-style progress per lint pass, and a realistically scrambled `package.json` (many top-level keys all needing to move several positions, several nested objects also needing sorting) was confirmed directly to need up to 11 fix passes to fully converge -- one more than ESLint's own `Linter#verifyAndFix` will ever run (`MAX_AUTOFIX_PASSES` is 10), meaning a single real `eslint --fix` invocation could leave such a file only partially reordered. Computing the whole target order up front and replacing every affected key's position in one combined fix converges in a single pass regardless of how scrambled the input is.
+*/
+function computeOrderPermutation(keys, isValidOrder) {
+	return keys.map((_, index) => index).map((index) => ({
+		key: keys[index] ?? "",
+		index
+	})).sort((a, b) => {
+		if (isValidOrder(a.key, b.key) && isValidOrder(b.key, a.key)) return a.index - b.index;
+		return isValidOrder(a.key, b.key) ? -1 : 1;
+	}).map((entry) => entry.index);
+}
+function isIdentityPermutation(permutation) {
+	return permutation.every((originalIndex, position) => originalIndex === position);
+}
+function isStringNode(node) {
+	return node.type === "String";
+}
+function getMemberKeyName(member) {
+	return member.name.type === "String" ? member.name.value : void 0;
+}
+function hasRange(node) {
+	return node.range !== void 0;
+}
+const commentTypes = /* @__PURE__ */ new Set(["LineComment", "BlockComment"]);
+/**
+* Enforces the same `package.json` key order `syncpack format` would produce: `sortFirst` fields pinned to the top in that exact order, then every other top-level key alphabetically; and, inside each `sortAz`-listed field's own object or array value, its members/elements sorted the same way (no pinning there -- `sortFirst` only ever applies at the top level).
+*
+* This exists so a project using `@exadev/eslint-config` without syncpack still gets real `package.json` canonicalization, and so a project using both never sees them fight: `eslint --fix` and `syncpack format` converge on the identical output, confirmed directly against real `syncpack@15` output rather than assumed from its docs (see `compareSyncpackKey`'s own comment). Deliberately narrower than `@eslint/json`'s own `sort-keys` rule, which only supports a single alphabetical order for every key with no field-specific pinning -- not a fit for syncpack's own two-tier scheme.
+*
+* Not part of `plugin.configs.recommended`: opt-in, the same tri-state shape as `react`/`nextjs` (see `docs.md`'s own usage example), since a project without syncpack needs to choose this deliberately, and a project with syncpack needs to confirm the two tools agree before turning it on.
+*/
+const packageJsonKeyOrder = {
+	meta: {
+		type: "layout",
+		fixable: "code",
+		languages: ["json/json", "json/jsonc"],
+		docs: {
+			recommended: false,
+			description: "Require package.json keys to be ordered the same way `syncpack format` would order them.",
+			url: "https://github.com/ExaDev/eslint-config/blob/main/src/rules/package-json-key-order.ts"
+		},
+		schema: [{
+			type: "object",
+			properties: {
+				sortFirst: {
+					type: "array",
+					items: { type: "string" }
+				},
+				sortAz: {
+					type: "array",
+					items: { type: "string" }
+				}
+			},
+			additionalProperties: false
+		}],
+		defaultOptions: [{}],
+		messages: { outOfOrder: "This key order does not match the order \"syncpack format\" would produce: \"{{curr}}\" should come before \"{{prev}}\" here." }
+	},
+	create(context) {
+		const [options] = context.options;
+		const sortFirst = options.sortFirst ?? DEFAULT_SORT_FIRST;
+		const sortAz = new Set(options.sortAz ?? DEFAULT_SORT_AZ);
+		const { sourceCode } = context;
+		function hasAdjacentComment(node) {
+			const before = sourceCode.getTokenBefore(node, { includeComments: true });
+			let after = sourceCode.getTokenAfter(node, { includeComments: true });
+			if (after?.type === "Comma") after = sourceCode.getTokenAfter(after, { includeComments: true });
+			return before !== null && commentTypes.has(before.type) || after !== null && commentTypes.has(after.type);
+		}
+		function buildReorderedText(nodes, permutation) {
+			const separators = nodes.slice(0, -1).map((node, index) => {
+				const next = nodes[index + 1];
+				return hasRange(node) && next !== void 0 && hasRange(next) ? sourceCode.text.slice(node.range[1], next.range[0]) : "";
+			});
+			return permutation.reduce((result, originalIndex, position) => {
+				const text = sourceCode.getText(nodes[originalIndex]);
+				return position === 0 ? text : `${result}${separators[position - 1] ?? ""}${text}`;
+			}, "");
+		}
+		function getNodeRanges(nodes) {
+			const ranges = [];
+			for (const node of nodes) {
+				if (!hasRange(node)) return void 0;
+				ranges.push(node.range);
+			}
+			return ranges;
+		}
+		function reportWholeContainerReorder(nodes, keys, isValidOrder, reportLoc) {
+			const permutation = computeOrderPermutation(keys, isValidOrder);
+			if (isIdentityPermutation(permutation)) return;
+			const firstNode = nodes[0];
+			const lastNode = nodes[nodes.length - 1];
+			if (firstNode === void 0 || lastNode === void 0) return;
+			let violationIndex = 1;
+			for (let index = 1; index < keys.length; index += 1) if (!isValidOrder(keys[index - 1] ?? "", keys[index] ?? "")) {
+				violationIndex = index;
+				break;
+			}
+			context.report({
+				loc: reportLoc(nodes[violationIndex] ?? firstNode),
+				messageId: "outOfOrder",
+				data: {
+					curr: keys[violationIndex] ?? "",
+					prev: keys[violationIndex - 1] ?? ""
+				},
+				fix(fixer) {
+					const ranges = getNodeRanges(nodes);
+					if (ranges === void 0 || nodes.some((node) => hasAdjacentComment(node))) return null;
+					const firstRange = ranges[0];
+					const lastRange = ranges[ranges.length - 1];
+					if (firstRange === void 0 || lastRange === void 0) return null;
+					const rewritten = buildReorderedText(nodes, permutation);
+					return fixer.replaceTextRange([firstRange[0], lastRange[1]], rewritten);
+				}
+			});
+		}
+		function checkMembers(members, isValidOrder) {
+			const keys = [];
+			for (const member of members) {
+				const key = getMemberKeyName(member);
+				if (key === void 0) return;
+				keys.push(key);
+			}
+			reportWholeContainerReorder(members, keys, isValidOrder, (member) => member.name.loc.start);
+		}
+		function checkElements(elements) {
+			const stringValues = [];
+			for (const element of elements) {
+				if (!isStringNode(element.value)) return;
+				stringValues.push(element.value);
+			}
+			reportWholeContainerReorder(stringValues, stringValues.map((value) => value.value), isValidSortAzOrder, (value) => value.loc.start);
+		}
+		return {
+			Object(node, parent) {
+				if (parent === void 0) return;
+				if (parent.type === "Document") {
+					checkMembers(node.members, (prev, curr) => isValidTopLevelOrder(prev, curr, sortFirst));
+					return;
+				}
+				if (parent.type === "Member") {
+					const key = getMemberKeyName(parent);
+					if (key !== void 0 && sortAz.has(key)) checkMembers(node.members, isValidSortAzOrder);
+				}
+			},
+			Array(node, parent) {
+				if (parent?.type !== "Member") return;
+				const key = getMemberKeyName(parent);
+				if (key !== void 0 && sortAz.has(key)) checkElements(node.elements);
+			}
+		};
+	}
+};
+//#endregion
 //#region src/rules/prefer-numeric-sort-compare.ts
 const createRule$2 = ESLintUtils.RuleCreator((name) => `https://github.com/ExaDev/eslint-config/blob/main/src/rules/${name}.ts`);
 const SORT_METHOD_NAMES = /* @__PURE__ */ new Set(["sort", "toSorted"]);
@@ -1424,6 +1634,7 @@ const plugin = {
 		"no-pointless-reassignment": noPointlessReassignment,
 		"no-set-instanceof-mutation": noSetInstanceofMutation,
 		"no-side-effects-in-index": noSideEffectsInIndex,
+		"package-json-key-order": packageJsonKeyOrder,
 		"prefer-numeric-sort-compare": preferNumericSortCompare,
 		"prefer-readonly-array-param": preferReadonlyArrayParam,
 		"prefer-readonly-object-param": preferReadonlyObjectParam
@@ -1457,6 +1668,69 @@ const plugin = {
 	}
 };
 //#endregion
+//#region src/package-json-key-order.ts
+const SYNCPACK_CONFIG_FILENAMES = [
+	".syncpackrc",
+	".syncpackrc.json",
+	".syncpackrc.yaml",
+	".syncpackrc.yml",
+	".syncpackrc.js",
+	".syncpackrc.cjs",
+	".syncpackrc.mjs",
+	"syncpack.config.js",
+	"syncpack.config.cjs",
+	"syncpack.config.mjs",
+	"syncpack.config.ts"
+];
+function packageJsonHasSyncpackKey(cwd) {
+	try {
+		const raw = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+		return typeof raw === "object" && raw !== null && "syncpack" in raw;
+	} catch {
+		return false;
+	}
+}
+/** Auto-detection signal for the `enabled: undefined` case: does this project already have syncpack configured? Mirrors the role `tryRequire`'s peer-package resolution plays for `react.ts`/`nextjs.ts`, but for a tool detected by config presence rather than by an installed package, since syncpack's own output is what this rule is emulating, not a peer this rule depends on. */
+function hasSyncpackConfig(cwd) {
+	return SYNCPACK_CONFIG_FILENAMES.some((filename) => existsSync(join(cwd, filename))) || packageJsonHasSyncpackKey(cwd);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isJsonLanguagePlugin(value) {
+	if (!isRecord(value)) return false;
+	const languages = value["languages"];
+	return isRecord(languages) && "json" in languages;
+}
+function resolveJsonPlugin(value) {
+	if (isRecord(value) && isJsonLanguagePlugin(value["default"])) return value["default"];
+	return isJsonLanguagePlugin(value) ? value : void 0;
+}
+const JSON_PLUGIN_INSTALL_COMMAND = "pnpm add -D @eslint/json";
+function buildPackageJsonKeyOrderConfig(options = {}) {
+	const cwd = options.cwd ?? process.cwd();
+	if (options.enabled === false) return [];
+	if (options.enabled === void 0 && hasSyncpackConfig(cwd)) return [];
+	const jsonPlugin = resolveJsonPlugin(tryRequire("@eslint/json", options.requireFn));
+	if (jsonPlugin === void 0) {
+		if (options.enabled === true) throw new Error(`@exadev/eslint-config: package.json key ordering was explicitly requested but '@eslint/json' could not be resolved. Install it with: ${JSON_PLUGIN_INSTALL_COMMAND}`);
+		return [];
+	}
+	const ruleOptions = {
+		...options.sortFirst !== void 0 && { sortFirst: options.sortFirst },
+		...options.sortAz !== void 0 && { sortAz: options.sortAz }
+	};
+	return [{
+		files: ["**/package.json"],
+		language: "json/json",
+		plugins: {
+			exadev: plugin,
+			json: jsonPlugin
+		},
+		rules: { "exadev/package-json-key-order": ["error", ruleOptions] }
+	}];
+}
+//#endregion
 //#region src/recommended-type-checked.ts
 const TEST_FILE_PATTERNS = "**/*.{test,spec}.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
 const JS_TS_FILE_PATTERNS = "**/*.{ts,tsx,mts,cts,js,jsx,mjs,cjs}";
@@ -1551,6 +1825,7 @@ function exadevConfig(options = {}, ...userConfigs) {
 		...jsonCanonicalConfig,
 		...buildReactConfig({ enabled: options.react }),
 		...buildNextjsConfig({ enabled: options.nextjs }),
+		...buildPackageJsonKeyOrderConfig({ enabled: options.packageJsonKeyOrder }),
 		...userConfigs
 	]);
 }

package/package.json

@@ -1,19 +1,44 @@
 {
   "name": "exadev-eslint-config",
-  "version": "2.14.0",
   "description": "Shared custom ESLint rules and plugin for ExaDev projects",
-  "type": "module",
-  "sideEffects": false,
-  "license": "MIT",
+  "version": "2.15.0",
+  "dependencies": {
+    "@eslint/js": "^10.0.1",
+    "@typescript-eslint/utils": "8.67.0",
+    "eslint-plugin-jsdoc": "64.3.6",
+    "eslint-plugin-json-canonical": "1.0.0",
+    "eslint-plugin-tsdoc": "^0.5.2",
+    "ts-api-utils": "^2.5.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@commitlint/cli": "^21.2.1",
+    "@commitlint/config-conventional": "^21.2.0",
+    "@eslint/json": "2.1.0",
+    "@humanwhocodes/momoa": "^3.3.13",
+    "@next/eslint-plugin-next": "^16.3.2",
+    "@semantic-release/changelog": "^7.0.0",
+    "@semantic-release/git": "^11.0.1",
+    "@types/node": "^24.9.2",
+    "@typescript-eslint/rule-tester": "^8.67.0",
+    "@vitest/coverage-v8": "^4.1.10",
+    "eslint": "^10.8.0",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.2.0",
+    "publint": "^0.3.21",
+    "semantic-release": "^25.0.8",
+    "tsdown": "^0.22.13",
+    "turbo": "^2.10.8",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.10"
+  },
   "engines": {
     "node": ">=20"
   },
-  "publishConfig": {
-    "access": "public"
-  },
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
   "exports": {
     ".": {
       "types": {
@@ -29,13 +54,12 @@
   ],
   "keywords": [
     "eslint",
-    "eslintplugin",
-    "eslint-plugin"
+    "eslint-plugin",
+    "eslintplugin"
   ],
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/ExaDev/eslint-config.git"
-  },
+  "license": "MIT",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
   "peerDependencies": {
     "@next/eslint-plugin-next": "^16.3.2",
     "eslint": ">=10.0.0",
@@ -59,48 +83,25 @@
       "optional": true
     }
   },
-  "devDependencies": {
-    "@arethetypeswrong/cli": "^0.18.5",
-    "@commitlint/cli": "^21.2.1",
-    "@commitlint/config-conventional": "^21.2.0",
-    "@eslint/json": "2.1.0",
-    "@next/eslint-plugin-next": "^16.3.2",
-    "@semantic-release/changelog": "^7.0.0",
-    "@semantic-release/git": "^11.0.1",
-    "@types/node": "^24.9.2",
-    "@typescript-eslint/rule-tester": "^8.67.0",
-    "@vitest/coverage-v8": "^4.1.10",
-    "eslint": "^10.8.0",
-    "eslint-plugin-jsx-a11y": "^6.10.2",
-    "eslint-plugin-react": "^7.37.5",
-    "eslint-plugin-react-hooks": "^7.1.1",
-    "husky": "^9.1.7",
-    "lint-staged": "^17.2.0",
-    "publint": "^0.3.21",
-    "semantic-release": "^25.0.8",
-    "tsdown": "^0.22.13",
-    "turbo": "^2.10.8",
-    "typescript": "^6.0.3",
-    "typescript-eslint": "^8.67.0",
-    "vitest": "^4.1.10"
+  "publishConfig": {
+    "access": "public"
   },
-  "dependencies": {
-    "@eslint/js": "^10.0.1",
-    "@typescript-eslint/utils": "8.67.0",
-    "eslint-plugin-jsdoc": "64.3.6",
-    "eslint-plugin-json-canonical": "1.0.0",
-    "eslint-plugin-tsdoc": "^0.5.2",
-    "ts-api-utils": "^2.5.0"
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExaDev/eslint-config.git"
   },
+  "sideEffects": false,
+  "type": "module",
+  "types": "./dist/index.d.ts",
   "scripts": {
-    "build": "turbo run _build",
     "_build": "tsdown",
-    "lint": "turbo run _lint",
     "_lint": "eslint . --fix --cache --max-warnings 0",
-    "typecheck": "turbo run _typecheck",
+    "_test": "vitest run",
     "_typecheck": "tsc -p tsconfig.json",
+    "build": "turbo run _build",
+    "lint": "turbo run _lint",
+    "release": "semantic-release",
     "test": "turbo run _test",
-    "_test": "vitest run",
-    "release": "semantic-release"
+    "typecheck": "turbo run _typecheck"
   }
 }