eslint-plugin-th-rules 2.7.1 → 3.0.0

package/README.md

@@ -5,9 +5,143 @@
 [![CodeQL](../../actions/workflows/codeql.yml/badge.svg)](../../actions/workflows/codeql.yml)
 [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/tomerh2001/eslint-plugin-th-rules/badge)](https://securityscorecards.dev/viewer/?uri=github.com/tomerh2001/eslint-plugin-th-rules)
 
-This repository contains custom ESLint rules to enhance code quality and consistency across projects.
+A set of custom ESLint rules designed to improve code quality, enforce consistency, and introduce development conventions across TypeScript, React, and JavaScript projects.
+
+This plugin provides:
+
+- Custom rules unique to this repository  
+- Recommended flat configs that bundle th-rules with popular third-party plugins  
+- Advanced composable config layers for consumers who want fine-grained control  
+
+---
+
+# Installation
+
+```bash
+npm install --save-dev eslint-plugin-th-rules
+```
+
+This plugin requires ESLint Flat Config (ESLint 8.21+).
+
+---
+
+# Usage
+
+The plugin exposes three public recommended configurations.
+
+These are the presets most users should consume.
+
+## Recommended (Full Opinionated)
+
+Includes:
+
+- All th-rules
+- External plugins (lodash, n, sonarjs, security)
+- Opinionated rule settings for externals
+
+```js
+// eslint.config.js
+import thRules from "eslint-plugin-th-rules";
+
+export default [
+  ...thRules.configs.recommended
+];
+```
+
+## Recommended + TypeScript
+
+Recommended plus full strict/stylistic TypeScript configurations.
+
+```js
+import thRules from "eslint-plugin-th-rules";
+
+export default [
+  ...thRules.configs["recommended-typescript"]
+];
+```
+
+## Recommended + React
+
+Recommended plus:
+
+- eslint-plugin-react
+- eslint-plugin-react-hooks
+- JSX Runtime rules
+
+```js
+import thRules from "eslint-plugin-th-rules";
+
+export default [
+  ...thRules.configs["recommended-react"]
+];
+```
+
+---
+
+# Advanced Composition (Optional)
+
+If you want total control, you may import internal composition layers.
+
+These layers are intentionally not included in `configs`, because they are not presets but building blocks.
+
+```js
+import {
+  coreBase,
+  externalsBase,
+  externalsOpinionated,
+  coreTypescript,
+  coreReact
+} from "eslint-plugin-th-rules";
+```
+
+### Only use th-rules
+
+```js
+export default [
+  ...coreBase
+];
+```
+
+### Add external plugins (unstyled)
+
+```js
+export default [
+  ...coreBase,
+  ...externalsBase
+];
+```
+
+### Add external plugins + th-rules opinions
+
+```js
+export default [
+  ...coreBase,
+  ...externalsBase,
+  ...externalsOpinionated
+];
+```
+
+### Add TypeScript or React extensions
+
+```js
+export default [
+  ...coreBase,
+  ...externalsBase,
+  ...externalsOpinionated,
+  ...coreTypescript,
+  ...coreReact
+];
+```
+
+---
+
+# Auto-Generated Rule Documentation
+
+The following section is generated via `eslint-doc-generator`.  
+Do not edit below this line.
 
 ## Rules
+
 <!-- begin auto-generated rules list -->
 
 💼 Configurations enabled in.\
@@ -17,16 +151,42 @@ This repository contains custom ESLint rules to enhance code quality and consist
 🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
 💡 Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
-| Name                                                             | Description                                                                                                                         | 💼      | 🔧 | 💡 |
-| :--------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------- | :------ | :- | :- |
-| [no-boolean-coercion](docs/rules/no-boolean-coercion.md)         | Disallow Boolean(value) or !!value. Enforce _.isNil(value) for scalar values and _.isEmpty(value) for strings, arrays, and objects. | ✅ ⚛️ 🟦 |    | 💡 |
-| [no-comments](docs/rules/no-comments.md)                         | Disallow comments except for specified allowed patterns.                                                                            | ✅ ⚛️ 🟦 | 🔧 |    |
-| [no-default-export](docs/rules/no-default-export.md)             | Convert unnamed default exports to named default exports based on the file name.                                                    | ✅ ⚛️ 🟦 | 🔧 |    |
-| [no-destructuring](docs/rules/no-destructuring.md)               | Disallow destructuring that does not meet certain conditions                                                                        | ✅ ⚛️ 🟦 |    |    |
-| [prefer-is-empty](docs/rules/prefer-is-empty.md)                 | Require _.isEmpty instead of length comparisons                                                                                     | ✅ ⚛️ 🟦 |    | 💡 |
-| [schemas-in-schemas-file](docs/rules/schemas-in-schemas-file.md) | Require Zod schema declarations to be placed in a .schemas.ts file                                                                  | ✅ ⚛️ 🟦 |    |    |
-| [top-level-functions](docs/rules/top-level-functions.md)         | Require all top-level functions to be named/regular functions.                                                                      | ✅ ⚛️ 🟦 | 🔧 |    |
-| [types-in-dts](docs/rules/types-in-dts.md)                       | Require TypeScript type declarations (type/interface/enum) to be placed in .d.ts files                                              | ✅ ⚛️ 🟦 |    |    |
+| Name                                                             | Description                                                                                                                                      | 💼      | 🔧 | 💡 |
+| :--------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- | :------ | :- | :- |
+| [no-boolean-coercion](docs/rules/no-boolean-coercion.md)         | Disallow Boolean(value) or !!value. Enforce explicit checks: !_.isNil(value) for scalars and !_.isEmpty(value) for strings, arrays, and objects. | ✅ ⚛️ 🟦 |    | 💡 |
+| [no-comments](docs/rules/no-comments.md)                         | Disallow comments except for specified allowed patterns.                                                                                         | ✅ ⚛️ 🟦 | 🔧 |    |
+| [no-default-export](docs/rules/no-default-export.md)             | Convert unnamed default exports to named default exports based on the file name.                                                                 | ✅ ⚛️ 🟦 | 🔧 |    |
+| [no-destructuring](docs/rules/no-destructuring.md)               | Disallow destructuring that does not meet certain conditions.                                                                                    | ✅ ⚛️ 🟦 |    |    |
+| [prefer-is-empty](docs/rules/prefer-is-empty.md)                 | Require _.isEmpty instead of length comparisons.                                                                                                 | ✅ ⚛️ 🟦 |    | 💡 |
+| [schemas-in-schemas-file](docs/rules/schemas-in-schemas-file.md) | Require Zod schema declarations to be placed in a .schemas.ts file.                                                                              | ✅ ⚛️ 🟦 |    |    |
+| [top-level-functions](docs/rules/top-level-functions.md)         | Require all top-level functions to be named regular functions.                                                                                   | ✅ ⚛️ 🟦 | 🔧 |    |
+| [types-in-dts](docs/rules/types-in-dts.md)                       | Require TypeScript type declarations (type/interface/enum) to be placed in .d.ts files.                                                          | ✅ ⚛️ 🟦 |    |    |
 
 <!-- end auto-generated rules list -->
 
+---
+
+# Updating Documentation
+
+Auto-generate rule docs:
+
+```bash
+npm run update:eslint-docs
+```
+
+Recommended command:
+
+```json
+"update:eslint-docs": "eslint-doc-generator \
+  --config-emoji \"recommended,✅\" \
+  --config-emoji \"recommended-react,⚛️\" \
+  --config-emoji \"recommended-typescript,🟦\""
+```
+
+Internal layers (`core-*`, `externals-*`) are not included because they are not presets.
+
+---
+
+# License
+
+MIT

package/dist/configs/bundles/recommended-react.d.ts

@@ -0,0 +1,199 @@
+import react from 'eslint-plugin-react';
+export declare const recommendedReact: ({
+    name: string;
+    plugins: {
+        'th-rules': {
+            rules: any;
+        };
+    };
+    languageOptions: {
+        ecmaVersion: string;
+        sourceType: string;
+        globals: {
+            afterAll: false;
+            afterEach: false;
+            beforeAll: false;
+            beforeEach: false;
+            describe: false;
+            expect: false;
+            fit: false;
+            it: false;
+            jest: false;
+            test: false;
+            xdescribe: false;
+            xit: false;
+            xtest: false;
+            AggregateError: false;
+            Array: false;
+            ArrayBuffer: false;
+            Atomics: false;
+            BigInt: false;
+            BigInt64Array: false;
+            BigUint64Array: false;
+            Boolean: false;
+            DataView: false;
+            Date: false;
+            decodeURI: false;
+            decodeURIComponent: false;
+            encodeURI: false;
+            encodeURIComponent: false;
+            Error: false;
+            escape: false;
+            eval: false;
+            EvalError: false;
+            FinalizationRegistry: false;
+            Float32Array: false;
+            Float64Array: false;
+            Function: false;
+            globalThis: false;
+            Infinity: false;
+            Int16Array: false;
+            Int32Array: false;
+            Int8Array: false;
+            Intl: false;
+            isFinite: false;
+            isNaN: false;
+            JSON: false;
+            Map: false;
+            Math: false;
+            NaN: false;
+            Number: false;
+            Object: false;
+            parseFloat: false;
+            parseInt: false;
+            Promise: false;
+            Proxy: false;
+            RangeError: false;
+            ReferenceError: false;
+            Reflect: false;
+            RegExp: false;
+            Set: false;
+            SharedArrayBuffer: false;
+            String: false;
+            Symbol: false;
+            SyntaxError: false;
+            TypeError: false;
+            Uint16Array: false;
+            Uint32Array: false;
+            Uint8Array: false;
+            Uint8ClampedArray: false;
+            undefined: false;
+            unescape: false;
+            URIError: false;
+            WeakMap: false;
+            WeakRef: false;
+            WeakSet: false;
+            __dirname: false;
+            __filename: false;
+            AbortController: false;
+            AbortSignal: false;
+            AsyncDisposableStack: false;
+            atob: false;
+            Blob: false;
+            BroadcastChannel: false;
+            btoa: false;
+            Buffer: false;
+            ByteLengthQueuingStrategy: false;
+            clearImmediate: false;
+            clearInterval: false;
+            clearTimeout: false;
+            CloseEvent: false;
+            CompressionStream: false;
+            console: false;
+            CountQueuingStrategy: false;
+            crypto: false;
+            Crypto: false;
+            CryptoKey: false;
+            CustomEvent: false;
+            DecompressionStream: false;
+            DisposableStack: false;
+            DOMException: false;
+            ErrorEvent: false;
+            Event: false;
+            EventTarget: false;
+            exports: true;
+            fetch: false;
+            File: false;
+            FormData: false;
+            global: false;
+            Headers: false;
+            localStorage: false;
+            MessageChannel: false;
+            MessageEvent: false;
+            MessagePort: false;
+            module: false;
+            navigator: false;
+            Navigator: false;
+            performance: false;
+            Performance: false;
+            PerformanceEntry: false;
+            PerformanceMark: false;
+            PerformanceMeasure: false;
+            PerformanceObserver: false;
+            PerformanceObserverEntryList: false;
+            PerformanceResourceTiming: false;
+            process: false;
+            queueMicrotask: false;
+            ReadableByteStreamController: false;
+            ReadableStream: false;
+            ReadableStreamBYOBReader: false;
+            ReadableStreamBYOBRequest: false;
+            ReadableStreamDefaultController: false;
+            ReadableStreamDefaultReader: false;
+            Request: false;
+            require: false;
+            Response: false;
+            sessionStorage: false;
+            setImmediate: false;
+            setInterval: false;
+            setTimeout: false;
+            Storage: false;
+            structuredClone: false;
+            SubtleCrypto: false;
+            SuppressedError: false;
+            TextDecoder: false;
+            TextDecoderStream: false;
+            TextEncoder: false;
+            TextEncoderStream: false;
+            TransformStream: false;
+            TransformStreamDefaultController: false;
+            URL: false;
+            URLPattern: false;
+            URLSearchParams: false;
+            WebAssembly: false;
+            WebSocket: false;
+            WritableStream: false;
+            WritableStreamDefaultController: false;
+            WritableStreamDefaultWriter: false;
+        };
+    };
+    rules: Record<string, string>;
+} | {
+    name: string;
+    plugins: {
+        lodash: any;
+        n: import("@eslint/core", { with: { "resolution-mode": "require" } }).Plugin & {
+            configs: import("eslint-plugin-n").Configs;
+        };
+        sonarjs: typeof import("eslint-plugin-sonarjs");
+        security: typeof import("eslint-plugin-security");
+    };
+    rules: {};
+} | {
+    name: string;
+    rules: {
+        'lodash/import-scope': string[];
+        'lodash/chaining': string[];
+        camelcase: string;
+        'security/detect-unsafe-regex': string;
+        'sonarjs/no-clear-text-protocols': string;
+    };
+} | {
+    name: string;
+    rules: {
+        'react-hooks/set-state-in-effect': string;
+    };
+} | react.ReactFlatConfig | {
+    plugins: string[];
+    rules: import("eslint").Linter.RulesRecord;
+})[];

package/dist/configs/bundles/recommended-react.js

@@ -0,0 +1,11 @@
+import react from 'eslint-plugin-react';
+import reactHooks from 'eslint-plugin-react-hooks';
+import { coreReact } from '../core/react.js';
+import { recommended } from './recommended.js';
+export const recommendedReact = [
+    ...recommended,
+    react.configs.flat.recommended,
+    react.configs.flat['jsx-runtime'],
+    reactHooks.configs.recommended,
+    ...coreReact,
+];

package/dist/configs/bundles/recommended-typescript.d.ts

@@ -0,0 +1,190 @@
+export declare const recommendedTypescript: ({
+    name: string;
+    plugins: {
+        'th-rules': {
+            rules: any;
+        };
+    };
+    languageOptions: {
+        ecmaVersion: string;
+        sourceType: string;
+        globals: {
+            afterAll: false;
+            afterEach: false;
+            beforeAll: false;
+            beforeEach: false;
+            describe: false;
+            expect: false;
+            fit: false;
+            it: false;
+            jest: false;
+            test: false;
+            xdescribe: false;
+            xit: false;
+            xtest: false;
+            AggregateError: false;
+            Array: false;
+            ArrayBuffer: false;
+            Atomics: false;
+            BigInt: false;
+            BigInt64Array: false;
+            BigUint64Array: false;
+            Boolean: false;
+            DataView: false;
+            Date: false;
+            decodeURI: false;
+            decodeURIComponent: false;
+            encodeURI: false;
+            encodeURIComponent: false;
+            Error: false;
+            escape: false;
+            eval: false;
+            EvalError: false;
+            FinalizationRegistry: false;
+            Float32Array: false;
+            Float64Array: false;
+            Function: false;
+            globalThis: false;
+            Infinity: false;
+            Int16Array: false;
+            Int32Array: false;
+            Int8Array: false;
+            Intl: false;
+            isFinite: false;
+            isNaN: false;
+            JSON: false;
+            Map: false;
+            Math: false;
+            NaN: false;
+            Number: false;
+            Object: false;
+            parseFloat: false;
+            parseInt: false;
+            Promise: false;
+            Proxy: false;
+            RangeError: false;
+            ReferenceError: false;
+            Reflect: false;
+            RegExp: false;
+            Set: false;
+            SharedArrayBuffer: false;
+            String: false;
+            Symbol: false;
+            SyntaxError: false;
+            TypeError: false;
+            Uint16Array: false;
+            Uint32Array: false;
+            Uint8Array: false;
+            Uint8ClampedArray: false;
+            undefined: false;
+            unescape: false;
+            URIError: false;
+            WeakMap: false;
+            WeakRef: false;
+            WeakSet: false;
+            __dirname: false;
+            __filename: false;
+            AbortController: false;
+            AbortSignal: false;
+            AsyncDisposableStack: false;
+            atob: false;
+            Blob: false;
+            BroadcastChannel: false;
+            btoa: false;
+            Buffer: false;
+            ByteLengthQueuingStrategy: false;
+            clearImmediate: false;
+            clearInterval: false;
+            clearTimeout: false;
+            CloseEvent: false;
+            CompressionStream: false;
+            console: false;
+            CountQueuingStrategy: false;
+            crypto: false;
+            Crypto: false;
+            CryptoKey: false;
+            CustomEvent: false;
+            DecompressionStream: false;
+            DisposableStack: false;
+            DOMException: false;
+            ErrorEvent: false;
+            Event: false;
+            EventTarget: false;
+            exports: true;
+            fetch: false;
+            File: false;
+            FormData: false;
+            global: false;
+            Headers: false;
+            localStorage: false;
+            MessageChannel: false;
+            MessageEvent: false;
+            MessagePort: false;
+            module: false;
+            navigator: false;
+            Navigator: false;
+            performance: false;
+            Performance: false;
+            PerformanceEntry: false;
+            PerformanceMark: false;
+            PerformanceMeasure: false;
+            PerformanceObserver: false;
+            PerformanceObserverEntryList: false;
+            PerformanceResourceTiming: false;
+            process: false;
+            queueMicrotask: false;
+            ReadableByteStreamController: false;
+            ReadableStream: false;
+            ReadableStreamBYOBReader: false;
+            ReadableStreamBYOBRequest: false;
+            ReadableStreamDefaultController: false;
+            ReadableStreamDefaultReader: false;
+            Request: false;
+            require: false;
+            Response: false;
+            sessionStorage: false;
+            setImmediate: false;
+            setInterval: false;
+            setTimeout: false;
+            Storage: false;
+            structuredClone: false;
+            SubtleCrypto: false;
+            SuppressedError: false;
+            TextDecoder: false;
+            TextDecoderStream: false;
+            TextEncoder: false;
+            TextEncoderStream: false;
+            TransformStream: false;
+            TransformStreamDefaultController: false;
+            URL: false;
+            URLPattern: false;
+            URLSearchParams: false;
+            WebAssembly: false;
+            WebSocket: false;
+            WritableStream: false;
+            WritableStreamDefaultController: false;
+            WritableStreamDefaultWriter: false;
+        };
+    };
+    rules: Record<string, string>;
+} | {
+    name: string;
+    plugins: {
+        lodash: any;
+        n: import("@eslint/core", { with: { "resolution-mode": "require" } }).Plugin & {
+            configs: import("eslint-plugin-n").Configs;
+        };
+        sonarjs: typeof import("eslint-plugin-sonarjs");
+        security: typeof import("eslint-plugin-security");
+    };
+    rules: {};
+} | {
+    name: string;
+    rules: {
+        'lodash/import-scope': string[];
+        'lodash/chaining': string[];
+        camelcase: string;
+        'security/detect-unsafe-regex': string;
+        'sonarjs/no-clear-text-protocols': string;
+    };
+} | import("typescript-eslint").ConfigWithExtends)[];

package/dist/configs/bundles/recommended-typescript.js

@@ -0,0 +1,6 @@
+import { coreTypescript } from '../core/typescript.js';
+import { recommended } from './recommended.js';
+export const recommendedTypescript = [
+    ...recommended,
+    ...coreTypescript,
+];