@open-xchange/linter-presets 0.0.1

package/lib/eslint/env/jest.js

@@ -0,0 +1,56 @@
+
+import jestPlugin from "eslint-plugin-jest";
+
+// functions ==================================================================
+
+/**
+ * Creates configuration objects with global symbols and linter rules for unit
+ * tests using Jest.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-jest`
+ *
+ * @param {import("./jest").EnvJestOptions} options
+ *  Configuration options for the environment.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function jest(options) {
+
+    // config properties
+    const { files, ignores = [], rules } = options;
+
+    return [{
+        files,
+        ignores,
+
+        // register rule implementations, globals
+        ...jestPlugin.configs["flat/recommended"],
+
+        // configure plugin rules
+        rules: {
+            // recommended rules
+            ...jestPlugin.configs["flat/recommended"].rules,
+            ...jestPlugin.configs["flat/style"].rules,
+            // extra rules
+            "jest/consistent-test-it": ["error", { fn: "it" }],
+            "jest/no-commented-out-tests": "error",
+            "jest/no-conditional-expect": "off",
+            "jest/no-confusing-set-timeout": "error",
+            "jest/no-duplicate-hooks": "error",
+            "jest/no-test-return-statement": "error",
+            "jest/prefer-comparison-matcher": "error",
+            "jest/prefer-equality-matcher": "error",
+            "jest/prefer-expect-resolves": "error",
+            "jest/prefer-hooks-on-top": "error",
+            "jest/prefer-lowercase-title": "error",
+            "jest/prefer-mock-promise-shorthand": "error",
+            "jest/prefer-spy-on": "error",
+            "jest/prefer-todo": "error",
+            "jest/require-top-level-describe": "error",
+            // custom rules
+            ...rules,
+        },
+    }];
+}

package/lib/eslint/env/node.d.ts

@@ -0,0 +1,21 @@
+
+import { FlatConfigArray, LanguageOptions, EnvBaseOptions } from "../shared/types.js";
+
+// types ======================================================================
+
+/**
+ * Configuration options for the environment preset "env.node".
+ */
+export interface EnvNodeOptions extends EnvBaseOptions {
+
+    /**
+     * The module mode used by the linted files.
+     *
+     * Default value is "module".
+     */
+    sourceType?: LanguageOptions["sourceType"];
+}
+
+// functions ==================================================================
+
+export default function node(options: EnvNodeOptions): FlatConfigArray;

package/lib/eslint/env/node.js

@@ -0,0 +1,59 @@
+
+// replacement for abandoned "eslint-plugin-node"
+// - https://github.com/mysticatea/eslint-plugin-node/issues/341
+import nodePlugin from "eslint-plugin-n";
+
+import { RESTRICTED_GLOBALS, RESTRICTED_SYNTAX } from "../shared/constants.js";
+
+// functions ==================================================================
+
+/**
+ * Creates configuration objects with global symbols and linter rules for
+ * NodeJS modules.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-n`
+ *
+ * @param {import("./node").EnvNodeOptions} options
+ *  Configuration options for the environment.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function node(options) {
+
+    // configuration properties
+    const { files, ignores = [], sourceType = "module", rules } = options;
+    // the plugin configuration
+    const configKey = (sourceType === "commonjs") ? "flat/recommended-script" : "flat/recommended-module";
+    const nodeConfig = nodePlugin.configs[configKey];
+
+    return [
+
+        // register rule implementations and global symbols
+        {
+            files,
+            ignores,
+            ...nodeConfig,
+            // automatically add missing extensions in imports of CommonJS scripts
+            settings: {
+                node: {
+                    tryExtensions: [".js", ".ts"],
+                },
+            },
+        },
+
+        // reconfigure plugin rules
+        {
+            files,
+            ignores,
+            rules: {
+                "no-restricted-globals": ["error", ...RESTRICTED_GLOBALS],
+                "no-restricted-syntax": ["error", ...RESTRICTED_SYNTAX],
+                "n/no-unsupported-features/node-builtins": ["error", { allowExperimental: true }],
+                "n/prefer-node-protocol": "error",
+                ...rules,
+            },
+        },
+    ];
+}

package/lib/eslint/env/plugin.d.ts

@@ -0,0 +1,13 @@
+
+import { FlatConfigArray, EnvBaseOptions } from "../shared/types.js";
+
+// types ======================================================================
+
+/**
+ * Configuration options for the environment preset "env.plugin".
+ */
+export interface EnvPluginOptions extends EnvBaseOptions { }
+
+// functions ==================================================================
+
+export default function plugin(options: EnvPluginOptions): FlatConfigArray;

package/lib/eslint/env/plugin.js

@@ -0,0 +1,61 @@
+/*
+ * @copyright Copyright (c) Open-Xchange GmbH, Germany <info@open-xchange.com>
+ * @license AGPL-3.0
+ *
+ * This code is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published by
+ * the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with OX App Suite. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
+ *
+ * Any use of the work other than as authorized under this license or copyright law is prohibited.
+ *
+ */
+
+import eslintPlugin from "eslint-plugin-eslint-plugin";
+
+// exports ====================================================================
+
+/**
+ * Adds linter rules for ESLint plugin implementations.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-eslint-plugin`
+ *
+ * @param {import("./plugin").EnvPluginOptions} options
+ *  Configuration options for the environment.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function plugin(options) {
+
+    // configuration properties
+    const { files, ignores = [], rules = {} } = options;
+    // the plugin configuration
+    const pluginConfig = eslintPlugin.configs["flat/rules-recommended"];
+
+    return [
+
+        // register rule implementations and recommended rules
+        {
+            files,
+            ignores,
+            ...pluginConfig,
+        },
+
+        // reconfigure plugin rules
+        {
+            files,
+            ignores,
+            rules,
+        },
+    ];
+}

package/lib/eslint/env/react.d.ts

@@ -0,0 +1,19 @@
+
+import { FlatConfigArray, EnvBaseOptions } from "../shared/types.js";
+
+// types ======================================================================
+
+/**
+ * Configuration options for the environment preset "env.react".
+ */
+export interface EnvReactOptions extends EnvBaseOptions {
+
+    /**
+     * Configuration for the rule "react-hooks-static-deps/exhaustive-deps".
+     */
+    staticHooks?: Record<string, boolean | readonly boolean[] | Record<string, boolean>>;
+}
+
+// functions ==================================================================
+
+export default function react(options: EnvReactOptions): FlatConfigArray;

package/lib/eslint/env/react.js

@@ -0,0 +1,103 @@
+
+import { fixupPluginRules } from "@eslint/compat";
+import reactPlugin from "eslint-plugin-react";
+import reactHooksPlugin from "eslint-plugin-react-hooks";
+import reactHooksStaticDepsPlugin from "eslint-plugin-react-hooks-static-deps";
+import reactRefreshPlugin from "eslint-plugin-react-refresh";
+import jsxExpressionsPlugin from "eslint-plugin-jsx-expressions";
+import jsxA11yPlugin from "eslint-plugin-jsx-a11y";
+
+// functions ==================================================================
+
+/**
+ * Creates configuration objects with linter rules for ReactJS.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-react`
+ * - `eslint-plugin-react-hooks`
+ * - `eslint-plugin-react-hooks-static-deps`
+ * - `eslint-plugin-react-refresh`
+ * - `eslint-plugin-jsx-expressions`
+ * - `eslint-plugin-jsx-a11y`
+ *
+ * @param {import("./react").EnvReactOptions} options
+ *  Configuration options for the environment.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function react(options) {
+
+    // configuration properties
+    const { files, ignores = [], rules, staticHooks = {} } = options;
+
+    return [
+
+        // configure plugins and rules for all source files (JSX and TSX)
+        {
+            files,
+            ignores,
+
+            // register rule implementations of the plugins
+            plugins: {
+                react: fixupPluginRules(reactPlugin), // https://github.com/jsx-eslint/eslint-plugin-react/issues/3699
+                "react-hooks": reactHooksPlugin,
+                "react-hooks-static-deps": fixupPluginRules(reactHooksStaticDepsPlugin), // https://github.com/stoikio/eslint-plugin-react-hooks-static-deps/issues/1
+                "react-refresh": reactRefreshPlugin,
+                "jsx-expressions": fixupPluginRules(jsxExpressionsPlugin), // https://github.com/hluisson/eslint-plugin-jsx-expressions/issues/18
+                "jsx-a11y": jsxA11yPlugin,
+            },
+
+            settings: {
+                react: {
+                    version: "detect",
+                },
+            },
+
+            // enable JSX support
+            languageOptions: {
+                parserOptions: reactPlugin.configs.recommended.parserOptions,
+            },
+
+            // configure plugin rules
+            rules: {
+                // recommended rules
+                ...reactPlugin.configs.recommended.rules,
+                ...reactPlugin.configs["jsx-runtime"].rules,
+                ...reactHooksPlugin.configs.recommended.rules,
+                ...jsxA11yPlugin.flatConfigs.recommended.rules,
+                // "react" plugin: change or disable a few recommended rules
+                "react/hook-use-state": "error",
+                "react/iframe-missing-sandbox": "error",
+                "react/jsx-boolean-value": "error",
+                "react/jsx-no-script-url": "error",
+                "react/jsx-no-useless-fragment": "error",
+                "react/no-danger": "error",
+                "react/no-invalid-html-attribute": "error",
+                "react/no-typos": "error",
+                "react/prop-types": ["error", { skipUndeclared: true }],
+                "react/style-prop-object": "error",
+                "react/void-dom-elements-no-children": "error",
+                // replace "react-hooks/exhaustive-deps" rule with advanced alternative
+                "react-hooks/exhaustive-deps": "off",
+                "react-hooks-static-deps/exhaustive-deps": ["error", { staticHooks }],
+                // "react-refresh" plugin
+                "react-refresh/only-export-components": ["error", { allowConstantExport: true }],
+                // custom rules
+                ...rules,
+            },
+        },
+
+        // additional rules for TSX only
+        {
+            files,
+            ignores: [...ignores, "**/*.{js,jsx}"],
+
+            // configure plugin rules
+            rules: {
+                // replace "react/jsx-no-leaked-render" rule with advanced alternative
+                "jsx-expressions/strict-logical-expressions": "error",
+            },
+        },
+    ];
+}

package/lib/eslint/env/tsconfig.d.ts

@@ -0,0 +1,19 @@
+
+import { FlatConfigArray, EnvBaseOptions } from "../shared/types.js";
+
+// types ======================================================================
+
+/**
+ * Configuration options for the environment preset "env.tsconfig".
+ */
+export interface EnvTSConfigOptions extends EnvBaseOptions {
+
+    /**
+     * The path to the TypeScript project configuration file (`tsconfig.json`).
+     */
+    project: string;
+}
+
+// functions ==================================================================
+
+export default function tsconfig(options: EnvTSConfigOptions): FlatConfigArray;

package/lib/eslint/env/tsconfig.js

@@ -0,0 +1,37 @@
+
+// functions ==================================================================
+
+/**
+ * Creates configuration objects for TypeScript projects.
+ *
+ * @param {import("./tsconfig").EnvTSConfigOptions} options
+ *  Configuration options for the environment.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function tsconfig(options) {
+
+    // configuration properties
+    const { files, ignores = [], rules } = options;
+
+    return [{
+        files,
+        ignores,
+
+        // path to project configuration file
+        languageOptions: {
+            parserOptions: {
+                project: options.project,
+            },
+        },
+
+        // configure plugin rules
+        rules: {
+            // imports will be checked by TSC
+            "n/no-missing-import": "off",
+            // custom rules
+            ...rules,
+        },
+    }];
+}

package/lib/eslint/env/vitest.d.ts

@@ -0,0 +1,13 @@
+
+import { FlatConfigArray, EnvBaseOptions } from "../shared/types.js";
+
+// types ======================================================================
+
+/**
+ * Configuration options for the environment preset "env.vitest".
+ */
+export interface EnvVitestOptions extends EnvBaseOptions { }
+
+// functions ==================================================================
+
+export default function vitest(options: EnvVitestOptions): FlatConfigArray;

package/lib/eslint/env/vitest.js

@@ -0,0 +1,103 @@
+
+import { fixupPluginRules } from "@eslint/compat";
+import vitestPlugin from "eslint-plugin-vitest";
+import jestDomPlugin from "eslint-plugin-jest-dom";
+import testingLibraryPlugin from "eslint-plugin-testing-library";
+
+// functions ==================================================================
+
+/**
+ * Creates configuration objects with global symbols and linter rules for unit
+ * tests using Vitest.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-vitest`
+ * - `eslint-plugin-jest-dom`
+ * - `eslint-plugin-testing-library`
+ *
+ * @param {import("./vitest").EnvVitestOptions} options
+ *  Configuration options for the environment.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function vitest(options) {
+
+    // configuration properties
+    const { files, ignores = [], rules } = options;
+
+    return [
+
+        // "vitest" plugin
+        {
+            files,
+            ignores,
+
+            // register rule implementations of the plugins
+            plugins: {
+                vitest: vitestPlugin,
+            },
+
+            // register global symbols of Vitest
+            languageOptions: {
+                globals: vitestPlugin.environments.env.globals,
+            },
+
+            // configure plugin rules
+            rules: {
+                // recommended rules
+                ...vitestPlugin.configs.recommended.rules,
+                // extra rules
+                "vitest/consistent-test-it": "error",
+                "vitest/no-alias-methods": "error",
+                "vitest/no-disabled-tests": "warn",
+                "vitest/no-duplicate-hooks": "error",
+                "vitest/no-focused-tests": "error",
+                "vitest/no-standalone-expect": "error",
+                "vitest/no-test-prefixes": "error",
+                "vitest/no-test-return-statement": "error",
+                "vitest/prefer-comparison-matcher": "error",
+                "vitest/prefer-each": "error",
+                "vitest/prefer-equality-matcher": "error",
+                "vitest/prefer-expect-resolves": "error",
+                "vitest/prefer-hooks-in-order": "error",
+                "vitest/prefer-hooks-on-top": "error",
+                "vitest/prefer-mock-promise-shorthand": "error",
+                "vitest/prefer-spy-on": "error",
+                "vitest/prefer-strict-equal": "error",
+                "vitest/prefer-to-be": "error",
+                "vitest/prefer-to-contain": "error",
+                "vitest/prefer-to-have-length": "error",
+                "vitest/require-top-level-describe": "error",
+                // custom rules
+                ...rules,
+            },
+        },
+
+        // "jest-dom" plugin
+        {
+            files,
+            ignores,
+            ...jestDomPlugin.configs["flat/recommended"],
+        },
+
+        // "testing-library" plugin
+        {
+            files,
+            ignores,
+
+            // register rule implementations of the plugins
+            plugins: {
+                "testing-library": fixupPluginRules(testingLibraryPlugin), // https://github.com/testing-library/eslint-plugin-testing-library/issues/899
+            },
+
+            // configure plugin rules
+            rules: {
+                // recommended rules
+                ...testingLibraryPlugin.configs.react.rules,
+                // extra rules
+                "testing-library/no-node-access": ["error", { allowContainerFirstChild: true }],
+            },
+        },
+    ];
+}

package/lib/eslint/index.d.ts

@@ -0,0 +1,90 @@
+
+import { Linter } from "eslint";
+
+import { FlatConfigArray, LanguageOptions, StylisticOptions } from "./shared/types";
+
+import tsconfig from "./env/tsconfig";
+import node from "./env/node";
+import browser from "./env/browser";
+import jest from "./env/jest";
+import vitest from "./env/vitest";
+import codecept from "./env/codecept";
+import react from "./env/react";
+import plugin from "./env/plugin";
+
+// types ======================================================================
+
+/**
+ * Configuration options for linting the entire project.
+ */
+export interface ESLintPresetsOptions {
+
+    /**
+     * Glob patterns with all files and folders to be ignored by ESlint.
+     */
+    ignores?: readonly string[];
+
+    /**
+     * Full path to the template file containing the license header to be used
+     * in all source files. The function `resolver` helps to to convert a local
+     * path to an absolute path.
+     */
+    license?: string;
+
+    /**
+     * Configuration options for language and project setup.
+     */
+    language?: LanguageOptions;
+
+    /**
+     * Configuration options for code style.
+     */
+    stylistic?: StylisticOptions;
+
+    /**
+     * Additional linter rules to be added to the global configuration.
+     */
+    rules?: Linter.RulesRecord;
+}
+
+// environments ===============================================================
+
+/**
+ * A collection with all available environment presets.
+ */
+export const env: {
+    tsconfig: typeof tsconfig;
+    node: typeof node;
+    browser: typeof browser;
+    jest: typeof jest;
+    vitest: typeof vitest;
+    codecept: typeof codecept;
+    react: typeof react;
+    plugin: typeof plugin;
+};
+
+// functions ==================================================================
+
+/**
+ * Creates and returns a resolver function for file paths relative to the given
+ * base URL of a script file.
+ *
+ * @param url
+ *  The base URL of the calling script, usually `import.meta.url`.
+ *
+ * @returns
+ *  A function that converts relative file paths to absolute file paths.
+ */
+export function resolver(url: string): (file: string) => string;
+
+/**
+ * Defines standard configuration objects targeting the source files in the
+ * entire project.
+ *
+ * @param config
+ *  Plugin configuration.
+ *
+ * @returns
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export function configure(config?: ESLintPresetsOptions): FlatConfigArray;