@open-xchange/linter-presets 0.0.1

package/lib/eslint/config/jsdoc.js

@@ -0,0 +1,55 @@
+
+import jsdocPlugin from "eslint-plugin-jsdoc";
+
+// functions ==================================================================
+
+/**
+ * Checks the JSDoc comments in source files.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-jsdoc`
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function jsdoc() {
+
+    return [
+
+        // register rule implementations and recommended rules
+        jsdocPlugin.configs["flat/recommended-error"],
+
+        // general configuration
+        {
+            settings: {
+                jsdoc: {
+                    tagNamePreference: {
+                        // disallowed tags for ES6 keywords `const`, `class`, `extends`
+                        augments: false,
+                        class: false,
+                        const: false,
+                        constant: false,
+                        constructor: false,
+                        extends: false,
+                    },
+                },
+            },
+        },
+
+        // overrides for TypeScript files
+        {
+            files: ["**/*.{ts,tsx,cts,mts}"],
+            rules: {
+                ...jsdocPlugin.configs["flat/recommended-typescript-error"].rules,
+                "jsdoc/check-param-names": ["error", { allowExtraTrailingParamDocs: true }], // overload signatures
+            },
+        },
+
+        // configure plugin rules
+        {
+            rules: {
+                "jsdoc/tag-lines": "off",
+            },
+        },
+    ];
+}

package/lib/eslint/config/json.js

@@ -0,0 +1,37 @@
+
+import jsonPlugin from "eslint-plugin-jsonc";
+
+// functions ==================================================================
+
+/**
+ * Defines standard linting rules for JSON files.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-jsonc`
+ *
+ * @param {Required<import("../shared/types").StylisticOptions>} options
+ *  Resolved configuration options.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function json(options) {
+
+    return [
+
+        // register rule implementations and recommended rules
+        ...jsonPlugin.configs["flat/recommended-with-json"],
+
+        // reconfigure plugin rules
+        {
+            rules: {
+                "jsonc/array-bracket-spacing": "error",
+                "jsonc/comma-style": "error",
+                "jsonc/indent": ["error", options.indent],
+                "jsonc/key-spacing": ["error", { mode: "minimum" }],
+                "jsonc/no-irregular-whitespace": "error",
+                "jsonc/no-octal-escape": "error",
+            },
+        },
+    ];
+}

package/lib/eslint/config/license.js

@@ -0,0 +1,33 @@
+
+import licensePlugin from "eslint-plugin-license-header";
+
+// functions ==================================================================
+
+/**
+ * Checks the existence of license headers in source files.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-license-header`
+ *
+ * @param {string} path
+ *  Path to the template file containing the license header.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function license(path) {
+
+    return [{
+        files: ["**/*.{js,jsx,mjs,cjs,ts,tsx,mts,cts}"],
+
+        // register rule implementations of the plugin
+        plugins: {
+            "license-header": licensePlugin,
+        },
+
+        // configure plugin rules
+        rules: {
+            "license-header/header": ["error", path],
+        },
+    }];
+}

package/lib/eslint/config/promises.js

@@ -0,0 +1,33 @@
+
+import promisePlugin from "eslint-plugin-promise";
+
+// functions ==================================================================
+
+/**
+ * Checks for correct usage of native promises.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-promise`
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function promises() {
+
+    return [
+
+        // register rule implementations and recommended rules
+        promisePlugin.configs["flat/recommended"],
+
+        // reconfigure plugin rules
+        {
+            rules: {
+                "promise/always-return": ["error", { ignoreLastCallback: true }],
+                "promise/no-callback-in-promise": "off",
+                "promise/no-nesting": "error",      // warning => error
+                "promise/no-return-in-finally": "error",
+                "promise/valid-params": "error",    // warning => error
+            },
+        },
+    ];
+}

package/lib/eslint/config/stylistic.js

@@ -0,0 +1,123 @@
+
+import stylisticPlugin from "@stylistic/eslint-plugin";
+import migratePlugin from "@stylistic/eslint-plugin-migrate";
+
+// functions ==================================================================
+
+/**
+ * Defines standard (opinionated) linter rules for source code style.
+ *
+ * Wraps the following packages:
+ * - `@stylistic/eslint-plugin`
+ * - `@stylistic/eslint-plugin-migrate`
+ *
+ * @param {Required<import("../shared/types").StylisticOptions>} options
+ *  Resolved configuration options.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function stylistic(options) {
+
+    // configuration properties
+    const { indent, semi, quotes, dangle } = options;
+
+    return [
+
+        // globally disable all deprecated stylistic core rules
+        stylisticPlugin.configs["disable-legacy"],
+
+        // "@stylistic" plugin
+        {
+            // register rule implementations of the plugins
+            plugins: {
+                "@stylistic": stylisticPlugin,
+            },
+
+            // configure plugin rules
+            rules: {
+                "@stylistic/array-bracket-spacing": "error",
+                "@stylistic/arrow-spacing": "error",
+                "@stylistic/block-spacing": "error",
+                "@stylistic/brace-style": ["error", "1tbs", { allowSingleLine: true }],
+                "@stylistic/comma-dangle": (dangle === "always") ? ["error", "always-multiline"] : (dangle === "never") ? ["error", "never"] : "off",
+                "@stylistic/comma-spacing": "error",
+                "@stylistic/comma-style": "error",
+                "@stylistic/computed-property-spacing": "error",
+                "@stylistic/eol-last": "error",
+                "@stylistic/function-call-spacing": "error",
+                "@stylistic/generator-star-spacing": "error",
+                "@stylistic/indent": ["error", indent, { SwitchCase: 1, MemberExpression: "off", flatTernaryExpressions: true }],
+                "@stylistic/indent-binary-ops": ["error", indent],
+                "@stylistic/jsx-child-element-spacing": "error",
+                "@stylistic/jsx-curly-brace-presence": "error",
+                "@stylistic/jsx-curly-spacing": "error",
+                "@stylistic/jsx-equals-spacing": "error",
+                "@stylistic/jsx-function-call-newline": "error",
+                "@stylistic/jsx-indent-props": ["error", indent],
+                "@stylistic/jsx-one-expression-per-line": "off",
+                "@stylistic/jsx-pascal-case": "error",
+                "@stylistic/jsx-quotes": "error",
+                "@stylistic/jsx-self-closing-comp": "error",
+                "@stylistic/jsx-wrap-multilines": "error",
+                "@stylistic/key-spacing": ["error", { mode: "minimum" }],
+                "@stylistic/keyword-spacing": "error",
+                "@stylistic/linebreak-style": "error",
+                "@stylistic/member-delimiter-style": "error",
+                "@stylistic/new-parens": "error",
+                "@stylistic/no-extra-semi": "error",
+                "@stylistic/no-floating-decimal": "error",
+                "@stylistic/no-mixed-operators": ["error", {
+                    groups: [
+                        // allow to mix arithmetic operators
+                        // ["+", "-", "*", "/", "%", "**"],
+                        ["&", "|", "^", "~", "<<", ">>", ">>>"],
+                        ["==", "!=", "===", "!==", ">", ">=", "<", "<="],
+                        ["&&", "||"],
+                        ["in", "instanceof"],
+                    ],
+                    allowSamePrecedence: true,
+                }],
+                "@stylistic/no-multiple-empty-lines": ["error", { max: 2 }],
+                "@stylistic/no-tabs": "error",
+                "@stylistic/no-trailing-spaces": "error",
+                "@stylistic/no-whitespace-before-property": "error",
+                "@stylistic/object-curly-spacing": ["error", "always"],
+                "@stylistic/quote-props": ["error", "as-needed"],
+                "@stylistic/quotes": (quotes === "off") ? "off" : ["error", quotes, { avoidEscape: true }],
+                "@stylistic/rest-spread-spacing": "error",
+                "@stylistic/semi": ["error", semi ? "always" : "never"],
+                "@stylistic/semi-spacing": "error",
+                "@stylistic/semi-style": "error",
+                "@stylistic/space-before-blocks": "error",
+                "@stylistic/space-before-function-paren": ["error", { anonymous: "always", named: "never", asyncArrow: "always" }],
+                "@stylistic/space-in-parens": "error",
+                "@stylistic/space-infix-ops": "error",
+                "@stylistic/space-unary-ops": "error",
+                "@stylistic/switch-colon-spacing": "error",
+                "@stylistic/template-curly-spacing": "error",
+                "@stylistic/template-tag-spacing": "error",
+                "@stylistic/type-annotation-spacing": "error",
+                "@stylistic/type-generic-spacing": "error",
+                "@stylistic/type-named-tuple-spacing": "error",
+                "@stylistic/wrap-iife": "error",
+                "@stylistic/yield-star-spacing": "error",
+            },
+        },
+
+        // "@stylistic/migrate" plugin
+        {
+            // register rule implementations of the plugins
+            plugins: {
+                "@stylistic/migrate": migratePlugin,
+            },
+
+            // configure plugin rules
+            rules: {
+                "@stylistic/migrate/migrate-js": "error",
+                "@stylistic/migrate/migrate-ts": "error",
+                "@stylistic/migrate/migrate-jsx": "error",
+            },
+        },
+    ];
+}

package/lib/eslint/config/ts.js

@@ -0,0 +1,100 @@
+/*
+* Copyright (C) Open-Xchange GmbH, Germany <info@open-xchange.com>
+*
+* This program is proprietary software and licensed to you under Open-Xchange
+* GmbH's Software License Agreement.
+*/
+
+import typescriptEslint from "typescript-eslint";
+
+import { NO_UNUSED_VARS_OPTIONS } from "../shared/constants.js";
+
+// functions ==================================================================
+
+/**
+ * Defines standard rules for TypeScript source files.
+ *
+ * Wraps the following packages:
+ * - `typescript-eslint`
+ *
+ * @returns {import("../shared/types.js").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function ts() {
+
+    // plugin configuration, additional rules
+    return typescriptEslint.config({
+        files: ["**/*.{ts,tsx,mts,cts}"],
+
+        // suppress warning for new TypeScript versions
+        languageOptions: {
+            parserOptions: {
+                warnOnUnsupportedTypeScriptVersion: false,
+            },
+        },
+
+        // recommended rules
+        extends: [
+            ...typescriptEslint.configs.recommendedTypeChecked,
+            ...typescriptEslint.configs.stylisticTypeChecked,
+        ],
+
+        // reconfigure plugin rules
+        rules: {
+            "@typescript-eslint/array-type": ["error", { default: "array-simple" }],
+            "@typescript-eslint/consistent-indexed-object-style": "off",
+            "@typescript-eslint/consistent-type-exports": "error",
+            "@typescript-eslint/consistent-type-imports": ["error", { disallowTypeAnnotations: false }],
+            "@typescript-eslint/default-param-last": "error",
+            "@typescript-eslint/dot-notation": "error",
+            "@typescript-eslint/explicit-function-return-type": ["error", {
+                allowExpressions: true,
+                allowTypedFunctionExpressions: true,
+                allowHigherOrderFunctions: true,
+                allowConciseArrowFunctionExpressionsStartingWithVoid: true,
+            }],
+            "@typescript-eslint/no-array-constructor": "error",
+            "@typescript-eslint/no-array-delete": "error",
+            "@typescript-eslint/no-duplicate-type-constituents": "error",
+            "@typescript-eslint/no-empty-function": ["error", {
+                allow: ["private-constructors", "protected-constructors", "decoratedFunctions", "overrideMethods"],
+            }],
+            "@typescript-eslint/no-empty-interface": "off",
+            "@typescript-eslint/no-explicit-any": "off",
+            "@typescript-eslint/no-import-type-side-effects": "error",
+            "@typescript-eslint/no-invalid-this": "error",
+            "@typescript-eslint/no-loop-func": "error",
+            "@typescript-eslint/no-mixed-enums": "error",
+            "@typescript-eslint/no-namespace": ["error", { allowDeclarations: true }],
+            "@typescript-eslint/no-non-null-assertion": "off",
+            "@typescript-eslint/no-redeclare": "error",
+            "@typescript-eslint/no-shadow": ["error", { ignoreOnInitialization: true }],
+            "@typescript-eslint/no-unnecessary-template-expression": "error",
+            "@typescript-eslint/no-unsafe-enum-comparison": "error",
+            "@typescript-eslint/no-unsafe-unary-minus": "error",
+            "@typescript-eslint/no-unused-vars": ["error", NO_UNUSED_VARS_OPTIONS],
+            "@typescript-eslint/no-useless-constructor": "error",
+            "@typescript-eslint/only-throw-error": "error",
+            "@typescript-eslint/prefer-find": "error",
+            "@typescript-eslint/prefer-literal-enum-member": "error",
+            "@typescript-eslint/prefer-nullish-coalescing": "off",
+            "@typescript-eslint/prefer-promise-reject-errors": "error",
+            "@typescript-eslint/prefer-readonly": "error",
+            "@typescript-eslint/require-await": "error",
+            "@typescript-eslint/restrict-template-expressions": "off",
+            "@typescript-eslint/return-await": ["error", "always"],
+            "@typescript-eslint/switch-exhaustiveness-check": "error",
+            "@typescript-eslint/use-unknown-in-catch-callback-variable": "error",
+        },
+    },
+
+    // fixes for module definition files
+    {
+        files: ["**/*.d.{ts,tsx,mts,cts}"],
+        rules: {
+            "@typescript-eslint/consistent-type-exports": "off",
+            "@typescript-eslint/consistent-type-imports": ["error", { prefer: "no-type-imports", disallowTypeAnnotations: false }],
+            "@typescript-eslint/no-extraneous-class": "off",
+        },
+    });
+}

package/lib/eslint/config/yaml.js

@@ -0,0 +1,34 @@
+
+import yamlPlugin from "eslint-plugin-yml";
+
+// functions ==================================================================
+
+/**
+ * Defines standard linting rules for YAML files.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-yml`
+ *
+ * @param {Required<import("../shared/types").StylisticOptions>} options
+ *  Resolved configuration options.
+ *
+ * @returns {import("../shared/types").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function yaml(options) {
+
+    return [
+
+        // register rule implementations and recommended rules
+        ...yamlPlugin.configs["flat/recommended"],
+
+        // reconfigure plugin rules
+        {
+            rules: {
+                "yml/indent": ["error", options.indent],
+                "yml/key-spacing": ["error", { mode: "minimum" }],
+                "yml/require-string-key": "error",
+            },
+        },
+    ];
+}

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

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

package/lib/eslint/env/browser.js

@@ -0,0 +1,127 @@
+
+import JAVASCRIPT_GLOBALS from "globals";
+import CONFUSING_BROWSER_GLOBALS from "confusing-browser-globals";
+
+import { RESTRICTED_GLOBALS, RESTRICTED_SYNTAX } from "../shared/constants.js";
+
+// constants ==================================================================
+
+/**
+ * Global builtin symbols that are confusing or deprecated.
+ */
+const CONFUSING_BUILTIN_GLOBALS = [
+    "constructor",
+    "escape",
+    "eval",
+    "hasOwnProperty",
+    "isPrototypeOf",
+    "propertyIsEnumerable",
+    "toLocaleString",
+    "toString",
+    "unescape",
+    "valueOf",
+];
+
+/**
+ * Global browser classes that may conflict with custom application classes.
+ * For disambiguation, custom classes must be imported, and global browser
+ * classes must be used with their fully qualified name.
+ */
+const AMBIGUOUS_BROWSER_TYPES = [
+    "Position",
+    "Point",
+    "Size",
+    "Range",
+    "Storage",
+    "Transformer",
+];
+
+// initialization =============================================================
+
+/**
+ * All supported global browser symbols intended to be used without fully
+ * qualified name (e.g. `HTMLElement` instead of `window.HTMLElement`).
+ * A few confusing globals will be filtered though, especially symbols with
+ * common names (e.g. `name`, `event`, etc.) to be able to catch missing or
+ * misspelled variables or parameter names.
+ */
+const BROWSER_GLOBALS = {};
+
+// Add all builtin ES globals.
+for (const name of Object.keys(JAVASCRIPT_GLOBALS.builtin)) {
+    BROWSER_GLOBALS[name] = "readonly";
+}
+
+// Add browser globals (skip writable properties, e.g. window event handlers).
+for (const [name, writable] of Object.entries(JAVASCRIPT_GLOBALS.browser)) {
+    if (!writable) { BROWSER_GLOBALS[name] = "readonly"; }
+}
+
+// Remove commonly known confusing or deprecated builtin globals.
+for (const name of CONFUSING_BUILTIN_GLOBALS) {
+    delete BROWSER_GLOBALS[name];
+}
+
+// Remove commonly known confusing browser globals (e.g. `name`, `event`).
+for (const name of CONFUSING_BROWSER_GLOBALS) {
+    delete BROWSER_GLOBALS[name];
+}
+
+// Create the configuration list for rule "no-restricted-globals".
+const AMBIGUOUS_BROWSER_GLOBALS = AMBIGUOUS_BROWSER_TYPES.map(name => {
+    const message = `Import custom type '${name}', or use 'window.${name}' for disambiguation.`;
+    return { name, message };
+});
+
+// functions ==================================================================
+
+/**
+ * Creates configuration objects with global symbols and linter rules for for
+ * browser modules.
+ *
+ * Wraps the following packages:
+ * - `globals`
+ * - `confusing-browser-globals`
+ *
+ * @param {import("./browser").EnvBrowserOptions} 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 browser(options) {
+
+    // configuration properties
+    const { files, ignores = [], rules } = options;
+
+    return [{
+        files,
+        ignores,
+
+        // register global symbols used in browser scripts
+        languageOptions: {
+            globals: BROWSER_GLOBALS,
+        },
+
+        // configure rules
+        rules: {
+            // ban specific browser globals
+            "no-restricted-globals": ["error",
+                ...RESTRICTED_GLOBALS,
+                ...AMBIGUOUS_BROWSER_GLOBALS,
+            ],
+            // ban static class functions
+            "no-restricted-properties": ["error",
+                { object: "Object", property: "hasOwn", message: "Missing browser support." },
+            ],
+            // ban specific syntax constructs
+            "no-restricted-syntax": ["error",
+                ...RESTRICTED_SYNTAX,
+                { selector: "ClassBody > StaticBlock", message: "Static blocks not supported yet." },
+                { selector: "ExportNamedDeclaration > TSEnumDeclaration[const=true]", message: "Do not export const enums." },
+            ],
+            // custom rules
+            ...rules,
+        },
+    }];
+}

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

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

package/lib/eslint/env/codecept.js

@@ -0,0 +1,70 @@
+/*
+* Copyright (C) Open-Xchange GmbH, Germany <info@open-xchange.com>
+*
+* This program is proprietary software and licensed to you under Open-Xchange
+* GmbH's Software License Agreement.
+*/
+
+import codeceptPlugin from "eslint-plugin-codeceptjs";
+import chaiExpectPlugin from "eslint-plugin-chai-expect";
+
+// functions ==================================================================
+
+/**
+ * Creates configuration objects with global symbols and linter rules for E2E
+ * tests using CodeceptJS.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-codeceptjs`
+ * - `eslint-plugin-chai-expect`
+ *
+ * @param {import("./codecept").EnvCodeceptOptions} 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 codecept(options) {
+
+    // configuration properties
+    const { files, ignores = [], rules } = options;
+
+    return [
+        {
+            files,
+            ignores,
+
+            // register rule implementations of the plugins
+            plugins: {
+                codeceptjs: codeceptPlugin,
+            },
+
+            // register global symbols of CodeceptJS
+            languageOptions: {
+                globals: {
+                    ...codeceptPlugin.environments.codeceptjs.globals,
+                },
+            },
+
+            // configure plugin rules
+            rules: {
+                // recommended rules
+                ...codeceptPlugin.configs.recommended.rules,
+                // extra rules
+                "new-cap": ["error", {
+                    capIsNewExceptions: ["After", "AfterSuite", "Before", "BeforeSuite", "Feature", "Scenario"],
+                }],
+                "no-restricted-properties": ["warn", { object: "Scenario", property: "todo", message: "Unexpected unimplemented test." }],
+                "codeceptjs/no-skipped-tests": "warn",
+                // custom rules
+                ...rules,
+            },
+        },
+
+        {
+            files,
+            ignores,
+            ...chaiExpectPlugin.configs["recommended-flat"],
+        },
+    ];
+}

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

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