eslint-config-un 1.0.0-beta.1 → 1.0.0-beta.2

package/README.md

@@ -4,7 +4,7 @@ Grown out of the personal collection of rules, an ESLint config aspiring to cove
 
 ## Features
 
-- **Every major plugin** is included (50+ in total): 
+- **Every major plugin** is included (100+ in total): 
   [![JavaScript](./assets/devicon-javascript.svg) Vanilla JS rules](https://eslint.org/docs/latest/rules),
   [![TypeScript] typescript-eslint](https://typescript-eslint.io/rules),
   [🦄unicorn](https://npmjs.com/eslint-plugin-unicorn),
@@ -138,7 +138,8 @@ export default eslintConfig({
 > [!NOTE]
 > We highly recommend using TypeScript config file, which is supported since ESLint v9.18.0, or [`@ts-check` directive](https://www.typescriptlang.org/docs/handbook/intro-to-js-ts.html#ts-check) at the start of the file otherwise.
 
-## List of configs
+<!-- eslint-disable-next-line markdown-preferences/heading-casing -->
+## Configs and Sub-configs
 
 eslint-config-un has a concept of Configs and Sub-configs, further referred to as Configs. 
 They are similar to ESLint flat config objects, but with some useful extensions.
@@ -148,12 +149,28 @@ You can enable any Config by setting it to `true` or an object with the Config's
 Passing `false` disables the Config. 
 Passing an empty array to `files` disables the Config, but not its' Sub-configs.
 
-<details>
-<summary>Config interface & docs</summary>
+Sub-config is a Config located within Config's options. 
+If the parent config is disabled by passing `false`, all its' Sub-configs are disabled too.
+
+After evaluating all the flat configs, eslint-config-un will **load only those plugins that were actually used**, unless `loadPluginsOnDemand` option is set to `false`.
+
+### Config (`UnConfig`) interface
 
 The Config has the following interface (exact types are simplified for docs):
 
 ```ts
+type Severity = 0 | 1 | 2 | 'off' | 'warn' | 'error';
+
+type RuleOptions = { /* ... pre-generated all rules' options */ };
+
+type UnRuleEntry<RuleName extends string> = Severity | [Severity, RuleOptions[RuleName]] | {
+  severity: Severity;
+  options?: RuleOptions[RuleName];
+  disableAutofix?: boolean;
+  files?: string[];
+  ignores?: string[];
+}
+
 type UnConfig =
   | boolean
   | {
@@ -162,43 +179,73 @@ type UnConfig =
 
       [RuleName in ('overrides' | 'overridesAny')]?: {
         [RuleName in string]:
-          | Severity
-          | [Severity, RuleOptions[RuleName]]
+          | UnRuleEntry<RuleName>
           | ((
               // These are severity and options *maybe* set by eslint-config-un
-              ourSeverity: Severity,
-              ourOptions?: RuleOptions[RuleName],
-            ) => Severity | [Severity, RuleOptions[RuleName]]);
+              unRuleSeverity: Severity,
+              unRuleOptions?: RuleOptions[RuleName],
+            ) => UnRuleEntry<RuleName>);
       };
 
       forceSeverity?: '2' | 'error' | '1' | 'warn';
-
       [`config${string}`]: UnConfig; // These are Sub-configs
-
       [customOptions: string]: unknown; // Custom options, individual for each Config
     };
-
-type Severity = 0 | 1 | 2 | 'off' | 'warn' | 'error';
 ```
 
-</details>
+#### `files` and `ignores`
 
-<br>
+They have exactly the same meaning as the corresponding ESLint flat config item properties, with the only difference being an empty array `[]` handling:
 
-- Sub-configs are the same as Configs, but configured within Config options. 
-  All Sub-configs use `configXXX` naming convention.
-- After evaluating all the flat configs, eslint-config-un will **load only those plugins that were actually used**, unless `loadPluginsOnDemand` option is set to `false`.
-- `files` and `ignores` have exactly the same meaning as the corresponding ESLint flat config item properties, with the only difference being an empty array `[]` handling:
-  - If you specify an empty array for `files`, the Config **will be disabled**, but of its' Sub-configs remain unaffected.
-  - If you specify an empty array for `ignores`, the default ignore list won't be used.
-- `overrides`/`overridesAny` is similar to ESLint's `rules`, but with a very important advantage: you can provide a function that will be called with the rule severity and options set by eslint-config-un, which allows you to **granularly override the options** or change the severity of each rule.
-  - The difference between `overrides` and `overridesAny` is that `overridesAny` will allow *any* rule to be overridden (from TypeScript's stand point; technically you can pass any rule to `overrides` too), while `overrides` will only allow those rules which are tied to the config.
-  - `overridesAny` will be applied **after** `overrides`.
-- `forceSeverity` allows to bulk override the severity of all the rules not overridden via `overrides` or `overridesAny`.
-- Custom options are individual for each Config and are documented in JSDoc format.
+- If you specify an empty array for `files`, the Config **will be disabled**, but of its' Sub-configs remain unaffected.
+- If you specify an empty array for `ignores`, the default ignore list won't be used.
+
+#### `overrides` and `overridesAny`
+
+These are similar to ESLint's `rules`, but with a very important advantage: you can provide a function that will be called with the rule severity and options set by eslint-config-un, which allows you to **granularly override the options** or change the severity of each rule.
+
+- The difference between `overrides` and `overridesAny` is that `overridesAny` will allow *any* rule to be overridden (from TypeScript's stand point; technically you can pass any rule to `overrides` too), while `overrides` will only allow those rules which are tied to the config.
+- `overridesAny` will be applied **after** `overrides`.
+
+#### Sub-configs
+
+Sub-configs are the same as Configs, but configured within Config options. 
+All Sub-configs use `configXXX` naming convention.
+
+#### `forceSeverity`
+
+Allows to bulk override the severity of all the rules not overridden via `overrides` or `overridesAny`.
+
+#### Custom options
+
+Custom options are individual for each Config and are documented in JSDoc format.
+
+### Rule entry (`UnRuleEntry`) interface
+
+#### `severity` and `options`
+
+Normal ESLint severity and rule options.
+
+#### `disableAutofix`
+
+Apply a copy of the rule with `disable-autofix/` prefix and all autofixes disabled.
+
+#### `files` and `ignores`
+
+Allows to limit to which files only the current rule will be applied.
+Only works if:
+
+- At least one of `files` or `ignores` is provided and non-empty;
+- `files` or the current Config is not an empty array.
+
+If these conditions are met, a separate Config will be created with:
+
+- `name` being the current Config's name with `/@rule/<rule name with prefix>` postfix;
+- `files` [intersected with the parent's `files`](https://eslint.org/docs/latest/use/configure/configuration-files#specifying-files-with-an-and-operation);
+- `ignores` merged with the parent's `ignores`.
+
+## List of configs
 
-Sub-config is a Config located within Config's options. 
-If the parent config is disabled by passing `false`, all its' Sub-configs are disabled too. 
 In the following table, Sub-configs have `/` in their names.
 
 ### Most popular and well known
@@ -369,7 +416,7 @@ In the following table, Sub-configs have `/` in their names.
 | `noSecrets/json`                                               | ✅                                          | ^                                                                                                 | Applied only to `.json` files by default                                                                                                 |
 | `expectType`                                                   | ❌                                          | [eslint-plugin-expect-type](https://npmjs.com/eslint-plugin-expect-type) (`expect-type`)          | Since v1.0.0                                                                                                                             |
 | `command`                                                      | ❌                                          | [eslint-plugin-command](https://npmjs.com/eslint-plugin-command) (`command`)                      | Since v1.0.0                                                                                                                             |
-| `antfu`                                                        | ❌                                          | [eslint-plugin-antfu](https://npmjs.com/eslint-plugin-antfu) (`antfu`)                            | Since v1.0.0<br>[Anthony Fu](https://antfu.me/)'s personal collection of rules.                                                          |
+| `antfu`                                                        | ❌                                          | [eslint-plugin-antfu](https://npmjs.com/eslint-plugin-antfu) (`antfu`)                            | Since v1.0.0<br>[Anthony Fu](https://antfu.me)'s personal collection of rules.                                                           |
 
 ## How to use
 
@@ -776,34 +823,45 @@ Please don't attempt to migrate to ESLint 9 and eslint-config-un at the same tim
 
 ### Migration guide
 
-We recommend that every step and sub-step below is done in a separate commit and on a separate git branch. 
+We recommend that every step and sub-step below is done in a separate commit and on a separate git branch.
+If necessary, any step should be additionally split into multiple commits.
 Before committing, please do also run tests, formatter, other linters and tools to ensure that nothing became broken, if you have any.
 
-1. Remove **ALL** ESLint related *dev* dependencies - be it plugins, parsers, whatever else or `eslint` itself. 
-   This ensures correct versions of plugins will be resolved by eslint-config-un and saves you from other weird and hard to debug problems.
-2. If you're using `.js` config file, we highly recommend that you migrate to `.ts` one, or at least add `@ts-check` TypeScript directive to the former. 
+1. Dependencies:
+   1. Remove **ALL** ESLint related *dev* dependencies - be it plugins, parsers, whatever else or `eslint` itself. 
+      This ensures correct versions of plugins will be resolved by eslint-config-un and saves you from other weird and hard to debug problems.
+   2. Install `eslint-config-un` following [the installation instructions](#installation).
+2. If you're using `.js` config file, we highly recommend that you migrate to `.ts` one, or at least add `@ts-check` TypeScript directive to the former.
    Please don't forget install [`jiti`](https://npmjs.com/jiti) for ESLint to able be to read your TypeScript config file.
 3. Following your intuition or/and configs' options JSDoc documentation, migrate the existing config to the closest eslint-config-un equivalent.
    1. Run ESLint for the first time (without `--fix`!). 
       The list of dependencies to be installed might be shown to you.
       Please review whether those plugins are actually used/needed and act accordingly: install necessary plugins and disable configs which require packages you do not wish to install.
    2. Rename rules on existing [`eslint` configuration comments](https://eslint.org/docs/latest/use/configure/rules#using-configuration-comments) if they have different plugin prefixes (the most common case is that `typescript-eslint` plugin has `ts` prefix in eslint-config-un instead of `@typescript-eslint`) **OR** change prefixes using [`pluginRenames` option](#plugin-prefixes-pluginrenames-option).
+      Look for `Definition for rule '<rule name>' was not found` comments
 4. Perform the following two steps in any order:
    1. Enable stylistic rules only and fix them automatically (if you wish to do so) by running ESLint with `--fix --fix-type problem,suggestion,layout` (the latter flag ensures auto removal of "unused" `eslint-disable` comments will not happen):
 
       ```ts
-      noStylisticRules: {
-        enableRules: {
-          rules: true,
-          disableAllOtherRules: true,
+      // ...
+      configs: {
+        // ...
+        noStylisticRules: {
+          enableRules: {
+            rules: true,
+            disableAllOtherRules: true,
+          },
         },
-      }
+        // ...
+      },
+      // ...
       ```
 
       **Note:** not every stylistic rule is auto-fixable and not all auto-fixes are safe to apply automatically (although we already maintain a list of rules for which we've disabled autofixes by default for these reasons).
 
       Please carefully review automatically applied fixes and do not forget about problems requiring manual intervention.
-   2. Set `configs.noStylisticRules` to `true` to disable purely stylistic rules and run ESLint for the first time with the new config. 
+      It might be worth to fix stylistic issues in two stages: auto and manually fixable problems.
+   2. Now set `configs.noStylisticRules` to `true` to disable purely stylistic rules and run ESLint for the first time with the new config. 
       Please don't use `--fix` option - this may complicate things as you will have less idea of what's changed (plus some autofixes may be unsafe to automatically apply). 
       Thoroughly go through the report and:
       - Decide which rules need to be disabled, enabled or changed the options of;

package/dist/config-un/cache.mjs

@@ -0,0 +1,133 @@
+import { createTraverser, groupBy, isObject, isPlainObject, omit, readAndParseJson, readFileSafe } from "../utils.mjs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import crypto from "node:crypto";
+import * as findUp from "empathic/find";
+import * as packageUtils from "empathic/package";
+import { LOCKS } from "package-manager-detector/constants";
+import { exec } from "tinyexec";
+
+//#region src/config-un/cache.ts
+const sha256 = (input) => {
+	const hashInstance = crypto.createHash("sha256");
+	if (typeof input === "string") hashInstance.update(input, "utf8");
+	else hashInstance.update(input);
+	return hashInstance.digest("hex");
+};
+const LOCKFILES_PER_PACKAGE_MANAGER = groupBy(Object.entries(LOCKS), ([, packageManager]) => packageManager);
+const ESLINT_FLAT_CONFIG_FILE_NAMES = [
+	"eslint.config.js",
+	"eslint.config.mjs",
+	"eslint.config.cjs",
+	"eslint.config.ts",
+	"eslint.config.mts",
+	"eslint.config.cts"
+];
+const computeCacheKey = async (context) => {
+	const result = [process.version, String(context.rootOptions.offlineMode)];
+	const packageManagerInfo = context.meta.usedPackageManager;
+	result.push(JSON.stringify(packageManagerInfo));
+	const gitignorePath = findUp.file(".gitignore");
+	const packageJsonPath = packageUtils.up();
+	const lockfilePaths = (packageManagerInfo ? LOCKFILES_PER_PACKAGE_MANAGER[packageManagerInfo.name].map(([lockfileName]) => lockfileName) : []).map((lockfileName) => findUp.file(lockfileName));
+	const eslintConfigPaths = ESLINT_FLAT_CONFIG_FILE_NAMES.map((eslintConfigFileName) => findUp.file(eslintConfigFileName));
+	const [gitHeadHashResult, ...filesToHash] = await Promise.all([
+		exec("git", ["rev-parse", "HEAD"]).then((v) => v, (error) => {
+			context.logger.warn("Error getting git HEAD hash:", error);
+			return null;
+		}),
+		gitignorePath && readFileSafe(gitignorePath, true),
+		packageJsonPath && readFileSafe(packageJsonPath, true),
+		Promise.all(lockfilePaths.map((lockfilePath) => lockfilePath ? readFileSafe(lockfilePath, true) : null)).then((files) => files.find((v) => v != null)),
+		Promise.all(eslintConfigPaths.map((eslintConfigPath) => eslintConfigPath ? readFileSafe(eslintConfigPath, true) : null)).then((files) => files.find((v) => v != null))
+	]);
+	result.push(gitHeadHashResult ? gitHeadHashResult.exitCode ? String(gitHeadHashResult.exitCode) : gitHeadHashResult.stdout : "", ...filesToHash.map((file) => file ? sha256(file) : ""));
+	return {
+		source: result,
+		hash: sha256(JSON.stringify(result))
+	};
+};
+const MAX_CACHE_VALID_MS = 36e5;
+const isCacheFresh = (cacheMetadata) => Date.now() < new Date(cacheMetadata.date).getTime() + MAX_CACHE_VALID_MS;
+const resolveCacheFilePath = (context) => {
+	const cachePath = packageUtils.cache("eslint-config-un", { create: true });
+	if (!cachePath) {
+		context.logger.warn("Could not determine the cache path");
+		return cachePath;
+	}
+	return path.join(cachePath, "config.json");
+};
+const saveCacheToFs = async (context, cacheData) => {
+	const cachePath = resolveCacheFilePath(context);
+	if (!cachePath) {
+		context.logger.warn("Could not determine cache path");
+		return false;
+	}
+	const { hash: cacheKey, source: cacheKeyRaw } = await computeCacheKey(context);
+	const dataToStore = {
+		date: (/* @__PURE__ */ new Date()).toISOString(),
+		key: cacheKey,
+		...cacheData,
+		usedParsers: Object.fromEntries(cacheData.usedParsers.entries()),
+		usedPackages: Object.fromEntries([...cacheData.usedPackages.entries()].map(([packageId, entries]) => [packageId, entries.map((info) => ({
+			...omit(info, ["valueTransformFn", "path"]),
+			property: [info.path, info.property].filter(Boolean).join("."),
+			...info.valueTransformFn && { valueTransformFn: [info.valueTransformFn.fn.toString(), info.valueTransformFn.scope] }
+		}))]))
+	};
+	let dataToStoreStringified;
+	try {
+		dataToStoreStringified = JSON.stringify(dataToStore);
+	} catch (error) {
+		context.logger.warn("Could not serialize configs to store in cache:", error);
+		return false;
+	}
+	const unserializablePaths = [];
+	createTraverser(dataToStore.configs).forEach(({ path: valuePath }, value) => {
+		if (typeof value === "function" || isObject(value) && !isPlainObject(value)) unserializablePaths.push([valuePath, value]);
+	});
+	if (unserializablePaths.length > 0) {
+		const unserializablePathsGrouped = Object.entries(groupBy(unserializablePaths, (v) => v[0][0])).map((values) => ({
+			configIndex: Number(values[0]),
+			configName: dataToStore.configs.at(Number(values[0]))?.name,
+			valuePaths: values[1].map(([valuePath]) => valuePath)
+		}));
+		context.logger.warn(`Could not serialize configs to store in cache because they contain unserializable data at paths:\n${unserializablePathsGrouped.map(({ configIndex, configName, valuePaths }) => `Config #${configIndex} ${configName ? `"${configName}"` : "[unnamed]"}:\n${valuePaths.map((valuePath) => `  - ${valuePath.slice(1).join(".")}`).join("\n")}`).join("\n")}`);
+		return false;
+	}
+	try {
+		await fs.writeFile(cachePath, dataToStoreStringified, "utf8");
+		context.debug(`Saved configs to cache, date: ${dataToStore.date}, key: ${cacheKeyRaw.join(",")}`);
+		return true;
+	} catch (error) {
+		context.logger.warn("Could not save cache data:", error);
+		return false;
+	}
+};
+const restoreCacheFromFs = async (context) => {
+	const cachePath = resolveCacheFilePath(context);
+	if (!cachePath) {
+		context.logger.warn("Could not determine cache path");
+		return null;
+	}
+	const [{ hash: cacheKey }, cachedData] = await Promise.all([computeCacheKey(context), readAndParseJson(cachePath)]);
+	if (cachedData?.key === cacheKey && Date.now() < new Date(cachedData.date).getTime() + MAX_CACHE_VALID_MS) return cachedData;
+	return null;
+};
+const saveCacheToMemory = async (context, data) => {
+	const cacheKey = await computeCacheKey(context);
+	globalThis.eslintConfigUnResolvedConfig = {
+		...data,
+		key: cacheKey.hash,
+		date: (/* @__PURE__ */ new Date()).toISOString()
+	};
+};
+const restoreCacheFromMemory = async (context) => {
+	const cacheKey = await computeCacheKey(context);
+	const configInMemory = globalThis.eslintConfigUnResolvedConfig;
+	if (configInMemory?.key === cacheKey.hash && isCacheFresh(configInMemory)) return configInMemory;
+	return null;
+};
+
+//#endregion
+export { restoreCacheFromFs, restoreCacheFromMemory, saveCacheToFs, saveCacheToMemory };

package/dist/config-un/config-utils.mjs

@@ -0,0 +1,76 @@
+import { arraify, styleConfigName, stylePackageName, styleText } from "../utils.mjs";
+import semver from "semver";
+
+//#region src/config-un/config-utils.ts
+const CONFIGS_MISC_GROUP_DISABLED_BY_DEFAULT = new Set([
+	"security",
+	"yaml",
+	"toml",
+	"json",
+	"jsonSchemaValidator",
+	"nodeDependencies",
+	"depend"
+]);
+const CONFIGS_TO_NOT_REPORT_IF_UNNECESSARILY_ENABLED_OR_DISABLED = new Set(["fileProgress"]);
+function getIsConfigEnabled(configName, defaultConditionOrPackageInstalled = true, { preCondition, requireAllListedPackagesToBeInstalled } = {}) {
+	const { configs = {}, defaultConfigsStatus } = this.rootOptions;
+	let enabledByUser;
+	let enabledBySystem;
+	let reason;
+	const providedConfig = configs[configName];
+	if (this.isTestMode) {
+		enabledBySystem ??= true;
+		reason ??= "all configs are enabled in the test mode";
+	}
+	if (providedConfig != null) {
+		enabledByUser ??= Boolean(providedConfig);
+		reason ??= "provided by the user";
+	}
+	if (defaultConfigsStatus === "all-disabled") {
+		enabledBySystem ??= false;
+		reason ??= "`defaultConfigsStatus` is set to `all-disabled`";
+	}
+	if (defaultConfigsStatus === "misc-enabled" && CONFIGS_MISC_GROUP_DISABLED_BY_DEFAULT.has(configName)) {
+		enabledBySystem ??= true;
+		reason ??= "`defaultConfigsStatus` is set to `misc-enabled` and the config is in the misc group";
+	}
+	if (typeof defaultConditionOrPackageInstalled === "string" || Array.isArray(defaultConditionOrPackageInstalled) && defaultConditionOrPackageInstalled.length > 0) {
+		const packagesList = arraify(defaultConditionOrPackageInstalled).map((packageNameAndMaybeVersionRange) => {
+			const [packageName = "", versionRangeToSatisfy] = packageNameAndMaybeVersionRange.split("|");
+			return {
+				packageName,
+				versionRangeToSatisfy
+			};
+		});
+		if (requireAllListedPackagesToBeInstalled && packagesList.length > 1) {
+			const notInstalledPackages = packagesList.filter(({ packageName, versionRangeToSatisfy }) => {
+				const packageInfo = this.packagesInfo[packageName];
+				return !packageInfo || versionRangeToSatisfy && !semver.satisfies(packageInfo.info.version, versionRangeToSatisfy);
+			});
+			enabledBySystem ??= notInstalledPackages.length === 0;
+			reason ??= `${enabledBySystem ? "all of these packages were installed" : `the following package${notInstalledPackages.length === 1 ? " is" : "s are"} not installed`}: ${(enabledBySystem ? packagesList : notInstalledPackages).map(({ packageName }) => stylePackageName(packageName)).join(", ")}`;
+		} else {
+			enabledBySystem ??= packagesList.some(({ packageName }) => {
+				const isInstalled = Boolean(this.packagesInfo[packageName]);
+				if (isInstalled) reason ??= `package ${stylePackageName(packageName)} is installed`;
+				return isInstalled;
+			});
+			reason ??= packagesList.length > 1 ? `neither of these packages are installed: ${packagesList.map(({ packageName }) => stylePackageName(packageName)).join(", ")}` : `package ${stylePackageName(packagesList[0]?.packageName || "")} is not installed`;
+		}
+	} else if (typeof defaultConditionOrPackageInstalled === "boolean") {
+		enabledBySystem ??= defaultConditionOrPackageInstalled;
+		reason ??= `config is ${defaultConditionOrPackageInstalled ? "enabled" : "disabled"} by default`;
+	}
+	if (preCondition) {
+		enabledBySystem &&= preCondition[0];
+		reason = `${reason} and the following condition was${enabledBySystem ? "" : styleText("redBright", " not")} met: ${preCondition[1]}`;
+	}
+	enabledBySystem ??= false;
+	if (typeof enabledByUser === "boolean" && typeof providedConfig === "boolean" && enabledByUser === enabledBySystem && !CONFIGS_TO_NOT_REPORT_IF_UNNECESSARILY_ENABLED_OR_DISABLED.has(configName)) this.logger.warn(`There is no need to ${enabledByUser ? "enable" : "disable"} \`${styleConfigName(configName)}\` config because this is the default`);
+	const isEnabled = enabledByUser ?? enabledBySystem;
+	this.debug(`Config \`${styleConfigName(configName)}\` is ${isEnabled ? styleText("green", "enabled") : styleText("red", "disabled")} because ${reason}`);
+	return isEnabled;
+}
+
+//#endregion
+export { getIsConfigEnabled };