@the-stranger/eslint-plugin 2.0.2 → 2.1.0

package/README.md

@@ -10,32 +10,20 @@ Requires Node.js 24+ and ESLint 9+.
 npm install --save-dev @the-stranger/eslint-plugin
 ```
 
-## Optional peer dependencies
-
-Install only the peers you need for the conditional presets:
-
-- `eslint-plugin-jest@^29.12.1`
-- `@vitest/eslint-plugin@^1.6.6`
-- `eslint-plugin-toml@^0.12.0` and `toml-eslint-parser@^0.10.1`
-- `@nx/eslint-plugin@21`
-
 ## Usage
 
 In your `eslint.config.js`, extend the presets you want:
 
 ```javascript
 import le from '@the-stranger/eslint-plugin'
-import leJest from '@the-stranger/eslint-plugin/configs/jest'
-import leVitest from '@the-stranger/eslint-plugin/configs/vitest'
-import leToml from '@the-stranger/eslint-plugin/configs/toml'
 import leNx from '@the-stranger/eslint-plugin/configs/nx'
-import { objectNamer, setRuleLevel } from '@the-stranger/eslint-plugin/utils'
+import { setRuleLevel } from '@the-stranger/eslint-plugin/utils'
 import { defineConfig } from 'eslint/config'
 
 export default defineConfig({
   extends: [
     // all-in-one
-    le.configs.recommended,
+    le.configs.standard,
 
     // or pick and choose
     le.configs.jsdoc,
@@ -47,29 +35,54 @@ export default defineConfig({
     le.configs.ts,
     le.configs.unicorn,
     le.configs.yml,
-
-    // conditional presets when peers are installed
-    leJest,
-    leVitest,
-    leToml,
-    leNx,
+    le.configs.vitest,
 
     // customization helpers
     setRuleLevel('error', le.configs.perfectionist),
-    objectNamer(le.configs.ts, 'my-eslint-config'),
   ],
 })
 ```
 
+## Optional peer dependencies
+
+Install [@nx/eslint-plugin] to enable the Nx preset:
+
+```bash
+npm install --save-dev @nx/eslint-plugin@^21
+```
+
+Then, in your ESLint config, extend the Nx preset:
+
+```javascript
+import leNx from '@the-stranger/eslint-plugin/nx'
+import { defineConfig } from 'eslint/config'
+
+export default defineConfig({
+  extends: [leNx],
+})
+```
+
 ## Configurations
 
-- **JSDoc**: Recommended config from [eslint-plugin-jsdoc] for both TypeScript and JavaScript files; allows the `@document` tag used by Docusaurus.
+- **All**: Includes every available preset in this package.
+- **Astro**: Uses [eslint-plugin-astro] with strict JSX accessibility checks.
+- **Base**: Minimal baseline config with no additional presets.
+- **Cypress**: Uses [eslint-plugin-cypress] recommended rules for Cypress tests.
+- **Jest**: Uses [eslint-plugin-jest]; aligned with the Vitest config for consistency.
+- **JSDoc**: Recommended config from [eslint-plugin-jsdoc] for both TypeScript and JavaScript files.
 - **JSONC**: Enables key and array sorting in JSON/JSONC documents using [eslint-plugin-jsonc].
 - **Node (n)**: Extends the recommended config from [eslint-plugin-n].
-- **Perfectionist**: Extends [eslint-plugin-perfectionist]; sorts all the things.
+- **Perfectionist**: Extends [eslint-plugin-perfectionist]; sorts all the things. Rules in this preset are set to "warn" by default.
 - **Promise**: Recommended rules from [eslint-plugin-promise].
+- **React**: Combines [@eslint-react/eslint-plugin], [eslint-plugin-react-hooks], [eslint-plugin-react-compiler], and [eslint-plugin-jsx-a11y].
+  - **React (type-checked)**: Extends the React preset with [eslint-react]'s strict type-checked config.
 - **Regexp**: Recommended rules from [eslint-plugin-regexp].
+- **Standard**: Curated default preset (Vitest + core linting presets) for most projects.
+- **TOML**: Uses [eslint-plugin-toml] and [toml-eslint-parser] to lint TOML files.
 - **TypeScript (ts)**: Sets up TypeScript linting via [typescript-eslint], disabling a few noisy rules; falls back when Nx is unavailable.
+  - **TypeScript (type-checked)**: Extends the TypeScript preset with rules that require type information.
+  - **TypeScript (type-checked strict)**: Extends the TypeScript preset with stricter rules.
+- **Vitest**: Uses [@vitest/eslint-plugin] to keep test files readable.
 - **Unicorn**: Recommended rules from [eslint-plugin-unicorn] with customizations.
 - **YAML**: Recommended config from [eslint-plugin-yml], plus key and array sorting via [yaml-eslint-parser].
 
@@ -77,25 +90,24 @@ export default defineConfig({
 
 These presets load only when their peer dependencies are present:
 
-- **Jest**: Uses [eslint-plugin-jest]; aligned with the Vitest rules for consistency.
-- **Vitest**: Uses [@vitest/eslint-plugin] to keep test files readable.
-- **TOML**: Uses [eslint-plugin-toml] and [toml-eslint-parser] to lint TOML files.
 - **Nx**: Extends Nx's recommended monorepo config from [@nx/eslint-plugin].
 
 ## Utilities
 
 - **getFilePatterns**: Generates glob patterns.
-- **namer**: Simple helper for naming config blocks.
-- **objectNamer**: Wraps a config object and assigns it a friendly name for reports.
-- **setRuleLevel**: Sets the severity of some or all rules in a config, handling nested configs.
+- **setRuleLevel**: Sets the severity of some or all rules in a config or an array of configs.
 
 <!-- Links -->
 
 [@nx/eslint-plugin]: https://nx.dev/docs/technologies/eslint/eslint-plugin/introduction
+[@eslint-react/eslint-plugin]: https://eslint-react.xyz
 [@vitest/eslint-plugin]: https://github.com/vitest-dev/eslint-plugin-vitest
 [eslint-plugin-jest]: https://github.com/jest-community/eslint-plugin-jest
 [eslint-plugin-jsdoc]: https://github.com/gajus/eslint-plugin-jsdoc
 [eslint-plugin-jsonc]: https://ota-meshi.github.io/eslint-plugin-jsonc
+[eslint-plugin-cypress]: https://github.com/cypress-io/eslint-plugin-cypress
+[eslint-plugin-react-compiler]: https://www.npmjs.com/package/eslint-plugin-react-compiler
+[eslint-plugin-react-hooks]: https://www.npmjs.com/package/eslint-plugin-react-hooks
 [eslint-plugin-n]: https://github.com/eslint-community/eslint-plugin-n
 [eslint-plugin-perfectionist]: https://perfectionist.dev
 [eslint-plugin-promise]: https://github.com/eslint-community/eslint-plugin-promise

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@the-stranger/eslint-plugin",
-  "version": "2.0.2",
+  "version": "2.1.0",
   "repository": {
-    "url": "git+https://github.com/the-chris-strange/the-stranger.git",
+    "type": "git",
+    "url": "https://github.com/the-chris-strange/the-stranger.git",
     "directory": "packages/eslint-plugin"
   },
   "type": "module",
   "exports": {
-    "./package.json": "./package.json",
     ".": {
       "types": "./src/index.d.ts",
       "import": "./src/index.js"
@@ -16,85 +16,39 @@
       "types": "./src/utils.d.ts",
       "import": "./src/utils.js"
     },
-    "./configs/jest": {
-      "types": "./src/lib/configs/jest.d.ts",
-      "import": "./src/lib/configs/jest.js"
-    },
-    "./configs/nx": {
-      "types": "./src/lib/configs/nx.d.ts",
-      "import": "./src/lib/configs/nx.js"
-    },
-    "./configs/toml": {
-      "types": "./src/lib/configs/toml.d.ts",
-      "import": "./src/lib/configs/toml.js"
-    },
-    "./configs/vitest": {
-      "types": "./src/lib/configs/vitest.d.ts",
-      "import": "./src/lib/configs/vitest.js"
-    }
+    "./package.json": "./package.json"
   },
+  "main": "./src/index.js",
+  "module": "./src/index.js",
+  "types": "./src/types.d.ts",
   "dependencies": {
-    "eslint-plugin-jsdoc": "^50.8.0",
-    "eslint-plugin-jsonc": "^2.21.0",
-    "eslint-plugin-n": "^17.23.2",
-    "eslint-plugin-perfectionist": "^4.15.1",
-    "eslint-plugin-promise": "^7.2.1",
-    "eslint-plugin-regexp": "^2.10.0",
-    "eslint-plugin-unicorn": "^59.0.1",
-    "eslint-plugin-yml": "^1.19.1",
-    "jsonc-eslint-parser": "^2.4.2",
-    "tslib": "^2.8.1",
-    "typescript-eslint": "^8.53.1",
-    "yaml-eslint-parser": "^1.3.2"
+    "@the-stranger/eslint-config": "^1.0.0",
+    "@the-stranger/eslint-utils": "^1.0.0",
+    "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@eslint/js": "^9.39.2",
-    "@nx/eslint": "21.6.4",
-    "@nx/eslint-plugin": "21.6.4",
-    "@nx/vite": "21.6.4",
-    "@types/node": "^24.10.9",
-    "@typescript-eslint/parser": "^8.53.1",
-    "@vitest/coverage-v8": "^3.2.4",
-    "@vitest/eslint-plugin": "^1.3.16",
-    "eslint": "^9.39.2",
+    "@nx/eslint": "22.5.2",
+    "@nx/eslint-plugin": "22.5.2",
+    "@nx/vitest": "22.5.2",
+    "@types/eslint-plugin-jsx-a11y": "^6.10.1",
+    "@types/node": "^24.12.2",
+    "@typescript-eslint/parser": "^8.58.2",
+    "@vitest/coverage-v8": "4.1.4",
+    "eslint": "^9.39.4",
     "eslint-config-prettier": "^10.1.8",
-    "eslint-plugin-eslint-plugin": "^7.3.0",
-    "eslint-plugin-jest": "^29.12.1",
-    "eslint-plugin-toml": "^0.12.0",
-    "nx": "21.6.4",
-    "prettier": "^3.8.0",
-    "prettier-plugin-packagejson": "^2.5.22",
-    "toml-eslint-parser": "^0.10.1",
+    "eslint-plugin-eslint-plugin": "^7.3.2",
+    "nx": "22.5.2",
+    "prettier": "^3.8.3",
+    "prettier-plugin-packagejson": "^3.0.2",
     "typescript": "^5.9.3",
-    "vite": "7.3.1",
-    "vitest": "^3.2.4"
+    "vite": "7.3.2",
+    "vitest": "4.1.4"
   },
   "peerDependencies": {
-    "@nx/eslint-plugin": "^21",
-    "@vitest/eslint-plugin": "^1.6.6",
     "eslint": "^9",
-    "eslint-plugin-jest": "^29.12.1",
-    "eslint-plugin-toml": "^0.12.0",
-    "toml-eslint-parser": "^0.10.1"
-  },
-  "peerDependenciesMeta": {
-    "@nx/eslint-plugin": {
-      "optional": true
-    },
-    "@vitest/eslint-plugin": {
-      "optional": true
-    },
-    "eslint-plugin-jest": {
-      "optional": true
-    },
-    "eslint-plugin-toml": {
-      "optional": true
-    },
-    "toml-eslint-parser": {
-      "optional": true
-    }
+    "typescript-eslint": "^8"
   },
   "engines": {
     "node": "^24"
   }
-}
+}

package/src/index.d.ts

@@ -1,3 +1,2 @@
-export { configs } from './lib/configs/index.js';
+export { configs } from './lib/configs.js';
 export { meta } from './lib/meta.js';
-//# sourceMappingURL=index.d.ts.map

package/src/index.js

@@ -1,2 +1,2 @@
-export { configs } from './lib/configs/index.js';
+export { configs } from './lib/configs.js';
 export { meta } from './lib/meta.js';

package/src/lib/configs.d.ts

@@ -0,0 +1,19 @@
+export declare const configs: {
+    readonly disableTypeChecked: {
+        name: string;
+        rules: {};
+    }[];
+    readonly json: import("eslint/config").Config[];
+    readonly recommended: import("eslint/config").Config[];
+    readonly 'recommended/astro': import("eslint/config").Config[];
+    readonly 'recommended/no-type-checked': import("eslint/config").Config[];
+    readonly 'recommended/react': import("eslint/config").Config[];
+    readonly 'recommended/strict': import("eslint/config").Config[];
+    readonly standard: import("eslint/config").Config[];
+    readonly 'standard/no-type-checked': import("eslint/config").Config[];
+    readonly 'standard/strict': import("eslint/config").Config[];
+    readonly 'tests/jest': import("eslint/config").Config[];
+    readonly 'tests/vitest': import("eslint/config").Config[];
+    readonly toml: import("eslint/config").Config[];
+    readonly yaml: import("eslint/config").Config[];
+};

package/src/lib/configs.js

@@ -0,0 +1,65 @@
+import { configure } from '@the-stranger/eslint-config';
+import { disableTypeCheckedConfig } from './disable-type-checked.js';
+import { disableExcept } from './utils/options.js';
+const recommendedSourceOptions = {
+    agentSkills: true,
+    js: true,
+    jsdoc: true,
+    node: true,
+    promise: true,
+    react: false,
+    regexp: true,
+    sort: true,
+    ts: { strict: false, typeChecked: true },
+    unicorn: true,
+};
+const recommendedReactOptions = {
+    ...recommendedSourceOptions,
+    react: {
+        astro: true,
+        typeChecked: true,
+        typescript: true,
+    },
+};
+const recommendedOptions = {
+    json: { sort: true },
+    nx: true,
+    source: recommendedSourceOptions,
+    tests: { unitTestRunner: 'vitest' },
+    yaml: { sort: true },
+};
+export const configs = {
+    'disableTypeChecked': disableTypeCheckedConfig,
+    'json': disableExcept({}, 'json'),
+    'recommended': configure(recommendedOptions),
+    'recommended/astro': configure({
+        ...recommendedOptions,
+        source: {
+            ...recommendedSourceOptions,
+            react: { astro: true, typeChecked: true, typescript: true },
+        },
+    }),
+    'recommended/no-type-checked': configure({
+        ...recommendedOptions,
+        source: { ...recommendedSourceOptions, ts: { strict: false, typeChecked: false } },
+    }),
+    'recommended/react': configure({
+        ...recommendedOptions,
+        source: recommendedReactOptions,
+    }),
+    'recommended/strict': configure({
+        ...recommendedOptions,
+        source: { ts: { strict: true, typeChecked: true } },
+    }),
+    'standard': configure(),
+    'standard/no-type-checked': configure({
+        source: { ts: { strict: false, typeChecked: false } },
+    }),
+    'standard/strict': configure({
+        source: { ts: { strict: true, typeChecked: true } },
+    }),
+    'tests/jest': disableExcept({ tests: { unitTestRunner: 'jest' } }, 'tests'),
+    'tests/vitest': disableExcept({ tests: { unitTestRunner: 'vitest' } }, 'tests'),
+    'toml': disableExcept({}, 'toml'),
+    'yaml': disableExcept({}, 'yaml'),
+};

package/src/lib/disable-type-checked.d.ts

@@ -0,0 +1,4 @@
+export declare const disableTypeCheckedConfig: {
+    name: string;
+    rules: {};
+}[];

package/src/lib/disable-type-checked.js

@@ -0,0 +1,8 @@
+import tseslint from 'typescript-eslint';
+import { namer } from './namer.js';
+export const disableTypeCheckedConfig = [
+    {
+        name: namer('disable-type-checked'),
+        rules: { ...tseslint.configs.disableTypeChecked.rules },
+    },
+];

package/src/lib/meta.d.ts

@@ -1,3 +1,2 @@
 import type { ESLint } from 'eslint';
 export declare const meta: ESLint.Plugin['meta'];
-//# sourceMappingURL=meta.d.ts.map

package/src/lib/namer.d.ts

@@ -1,12 +1,14 @@
 import type { Linter } from 'eslint';
 /**
  * Prepend the workspace's namespace or full name to a string. Useful for naming eslint configuration objects.
+ * @internal
  * @param value the value to add to the name
  * @returns prefixed value
  */
 export declare function namer(value?: string): string;
 /**
  * Set the `name` property of an ESLint config.
+ * @internal
  * @param config the object
  * @param defaultName override the default behavior of this function
  * @returns the named config(s)
@@ -14,6 +16,7 @@ export declare function namer(value?: string): string;
 export declare function objectNamer(config: Config, defaultName?: string): Named<Config>;
 /**
  * Make the name property of an object required. Preserves JSDoc comments for objects that already have a name property.
+ * @internal
  */
 export type Named<T extends object> = Required<T extends N ? Pick<T, 'name'> : N> & T;
 type Config = Linter.Config;
@@ -21,4 +24,3 @@ type N = {
     name?: string;
 };
 export {};
-//# sourceMappingURL=namer.d.ts.map

package/src/lib/namer.js

@@ -1,6 +1,7 @@
 import pkg from '../../package.json' with { type: 'json' };
 /**
  * Prepend the workspace's namespace or full name to a string. Useful for naming eslint configuration objects.
+ * @internal
  * @param value the value to add to the name
  * @returns prefixed value
  */
@@ -13,6 +14,7 @@ export function namer(value) {
 }
 /**
  * Set the `name` property of an ESLint config.
+ * @internal
  * @param config the object
  * @param defaultName override the default behavior of this function
  * @returns the named config(s)

package/src/lib/utils/get-module-root.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Get the expected root of a module. For package specifiers, returns the package root; for non-package-like specifiers, returns the value as-is.
+ * @param specifier the module specifier
+ * @returns the root module specifier
+ * @example
+ * getModuleRoot('pg') // -> 'pg'
+ * getModuleRoot('lodash/fp') // -> 'lodash'
+ * getModuleRoot('@scope/pkg') // -> '@scope/pkg'
+ * getModuleRoot('@scope/pkg/subpath') // -> '@scope/pkg'
+ */
+export declare function getModuleRoot(specifier: string): string;

package/src/lib/utils/get-module-root.js

@@ -0,0 +1,31 @@
+/**
+ * Get the expected root of a module. For package specifiers, returns the package root; for non-package-like specifiers, returns the value as-is.
+ * @param specifier the module specifier
+ * @returns the root module specifier
+ * @example
+ * getModuleRoot('pg') // -> 'pg'
+ * getModuleRoot('lodash/fp') // -> 'lodash'
+ * getModuleRoot('@scope/pkg') // -> '@scope/pkg'
+ * getModuleRoot('@scope/pkg/subpath') // -> '@scope/pkg'
+ */
+export function getModuleRoot(specifier) {
+    if (!specifier) {
+        return specifier;
+    }
+    if (specifier.startsWith('./') ||
+        specifier.startsWith('../') ||
+        specifier.startsWith('/') ||
+        specifier.startsWith('file:') ||
+        specifier.startsWith('node:')) {
+        return specifier;
+    }
+    if (specifier.startsWith('@')) {
+        const parts = specifier.split('/');
+        if (parts.length >= 2) {
+            return `${parts[0]}/${parts[1]}`;
+        }
+        return specifier;
+    }
+    const firstSlash = specifier.indexOf('/');
+    return firstSlash === -1 ? specifier : specifier.slice(0, firstSlash);
+}

package/src/lib/utils/optional-import-resolver.d.ts

@@ -0,0 +1,76 @@
+export declare class ImportResolver {
+    private allowSubpathMatch;
+    private cache;
+    private useCache;
+    constructor(options?: ImportResolverOptions);
+    clear(specifier?: string): void;
+    has(specifier: string): boolean;
+    import<T = unknown>(specifier: string): Promise<OptionalImportResult<T>>;
+    importDefault<T = unknown>(specifier: string): Promise<T | undefined>;
+    requireImport<T = unknown>(specifier: string): Promise<T | undefined>;
+    /**
+     * Narrow unknown to a Node-like error shape.
+     * @param value the value
+     * @returns the error-like object, or undefined if the value is not an object of the expected shape
+     */
+    private asNodeLikeError;
+    /**
+     * Extract the target from CommonJS-style error messages like:
+     * - Cannot find module 'pg'
+     * @param message the error message
+     * @returns the target, or undefined if the message doesn't match the expected pattern
+     */
+    private extractCannotFindModuleTarget;
+    /**
+     * Extract the quoted missing target from error messages like:
+     * - Cannot find package 'pg' imported from ...
+     * - Cannot find module 'pg' imported from ...
+     * @param message the error message
+     * @returns the target, or undefined if the message doesn't match the expected pattern
+     */
+    private extractQuotedMissingTarget;
+    /**
+     * Detect whether an import error means that the *requested* specifier is missing, as opposed to one of its transitive dependencies. This is necessarily heuristic because Node error shapes/messages vary by version.
+     * @param error the captured error
+     * @param specifier the value that was imported
+     * @returns true if the error is caused by the requested module; false otherwise
+     */
+    private isRequestedModuleMissing;
+    /**
+     * Determine whether the target is the requested module, or a subpath of it.
+     * @param target the identified target specifier
+     * @param requested the requested module specifier
+     * @returns true if {@link target} is a subpath of {@link requested}; false otherwise
+     * @example
+     * isSubpathOfModule('@scope/pkg/subpath', '@scope/pkg') // -> true
+     */
+    private isSameOrSubpath;
+    private loadModule;
+}
+export interface ImportResolverOptions {
+    /**
+     * Treat package subpaths as belonging to the same package.
+     * @default true
+     */
+    allowSubpathMatch?: boolean;
+    /**
+     * Cache resolved promises/results for each specifier.
+     * @default true
+     */
+    cache?: boolean;
+}
+export interface NodeLikeError {
+    code?: string;
+    message?: string;
+}
+/**
+ * The result of resolving an optional dependency.
+ * @template TModule the expected type of the imported module
+ */
+export type OptionalImportResult<TModule> = {
+    module: TModule;
+    success: true;
+} | {
+    module: undefined;
+    success: false;
+};