@open-xchange/linter-presets 0.0.1 → 0.0.3

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+## [0.0.1] - 2024-07-05
+
+- added: [ESLint] project configuration (core, js, ts, json, yaml, license, directives, promises, jsdoc, stylistic)
+- added: [ESLint] environment presets (tsconfig, node, browser, jest, vitest, codecept, react, plugin)
+
+## [0.0.2] - 2024-07-08
+
+- added: [StyleLint] project configuration (core, less, sass, license, stylistic)
+
+## [0.0.3] - 2024-07-09
+
+- added: [ESLint] `eslint-plugin-import`
+- added: [ESLint] option "restricted" for `env.node` and `env.browser`
+- added: [ESLint] custom rule `env-project/no-amd-module-directive`
+- added: [ESLint] custom rule `env-project/no-invalid-modules`
+- added: [ESLint] environment `env.project` (wraps all `env-project/*` rules)
+- changed: [ESLint] environment `env.plugin` renamed to `env.eslint`
+- fixed: [StyleLint] support for LESS files
+- chore: update dependencies

package/README.md

@@ -2,12 +2,6 @@
 
 This package provides configuration presets for [ESLint](https://eslint.org/) and [StyleLint](https://stylelint.io/), including wrappers for various linter plugins.
 
-## Utils
-
-The module `utils` exports utility functions for usage in either ESLint or StyleLint configuration files.
-
-See the [documentation](./doc/utils.md) for more details.
-
 ## ESLint
 
 The module `eslint` exports a `configure` function for setting up the entire project (e.g. TypeScript files, JSON files, license headers, etc.), and a set of environment presets that apply more ESLint plugins and rules to a specific subset of the project (e.g. browser code, unit test code, etc.).
@@ -32,8 +26,27 @@ export default [
 ]
 ```
 
-See the [documentation](./doc/eslint.md) for more details.
+See the [`eslint` module documentation](./lib/eslint/README.md) for more details.
 
 ## StyleLint
 
-See the [documentation](./doc/stylelint.md) for more details.
+The module `stylelint` exports a `configure` function for setting up the entire project (e.g. CSS files, SCSS files, license headers, etc.).
+
+Usage example:
+
+```js
+// stylelint.config.js
+import { stylelint } from "@open-xchange/linter-presets"
+
+export default eslint.configure({
+  /* config options */
+})
+```
+
+See the [`stylelint` module documentation](./lib/stylelint/README.md) for more details.
+
+## Utils
+
+The module `utils` exports utility functions to be used in ESLint and StyleLint configuration files.
+
+See the [`utils` module documentation](./lib/utils/README.md) for more details.

package/lib/eslint/README.md

@@ -0,0 +1,83 @@
+# ESLint Presets
+
+The module `eslint` provides a `configure` function for project-wide ESLint configuration (e.g. TypeScript files, JSON files, license headers, etc.), and a set of environment presets that apply more ESLint plugins and rules to a specific subset of the project (e.g. browser code, unit test code, etc.).
+
+## Functions
+
+### Function `configure`
+
+Generates standard configuration targeting the source files in the entire project. Internally, various ESLint plugins will be included and configured to use their recommended rule sets.
+
+| Target | ESLint Plugin |
+| - | - |
+| JavaScript and TypeScript files (including `.jsx` and `.tsx`) | ESLint core rules |
+| JavaScript files only (including `.jsx`) | ESLint core rules |
+| TypeScript files with type-aware rules (including `.tsx`) | [typescript-eslint](https://typescript-eslint.io/) |
+| JSON files | [eslint-plugin-jsonc](https://ota-meshi.github.io/eslint-plugin-jsonc/) |
+| YAML files | [eslint-plugin-yml](https://ota-meshi.github.io/eslint-plugin-yml/) |
+| License headers | [eslint-plugin-license-header](https://github.com/nikku/eslint-plugin-license-header) |
+| ESLint inline directives | [@eslint-community/eslint-plugin-eslint-comments](https://github.com/eslint-community/eslint-plugin-eslint-comments) |
+| Module imports | [eslint-plugin-import](https://github.com/import-js/eslint-plugin-import) |
+| Native ES6 promises | [eslint-plugin-promise](https://github.com/eslint-community/eslint-plugin-promise) |
+| JSDoc source documentation | [eslint-plugin-jsdoc](https://github.com/gajus/eslint-plugin-jsdoc) |
+| Source code formatting | [@stylistic/eslint-plugin](https://eslint.style/packages/default) |
+
+#### `configure` Signature
+
+```ts
+function configure(options?: ConfigureOptions): Linter.FlatConfig[]
+```
+
+#### `configure` Options
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `ignores` | `string[]` | `[]` | Glob patterns with all files and folders to be ignored by ESLint. |
+| `license` | `string` | `""` | Full path to the template file containing the license header to be used in all source files. |
+| `language` | `LanguageOptions` | | Configuration options for language and project setup. |
+| `language.ecmaVersion` | `number` | `2022` | The ECMAScript version to be used in the project (version or year). |
+| `language.sourceType` | `"module"\|"commonjs"` | `"module"` | Specifies how to treat `.js`, `.jsx`, `.ts`, and `.tsx` files. |
+| `stylistic` | `StylisticOptions` | | Configuration options for code style. |
+| `stylistic.indent` | `number` | `2` | Default indentation size (number of space characters). Will be applied to JavaScript, TypeScript, JSON, and YAML files, as well as JSX markup. |
+| `stylistic.semi` | `boolean` | `false` | Specifies whether to require semicolons following all statements (`true`), or to force to omit semicolons if possible according to ASI rules (`false`). |
+| `stylistic.quotes` | `"single"\|"double"\|"off"` | `"single"` | The type of the string delimiter character. |
+| `stylistic.dangle` | `"always"\|"never"\|"off"` | `"always"` | Specifies how to treat dangling commas in multiline lists. |
+| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the global configuration. |
+
+#### `configure` Example
+
+```js
+// eslint.config.js
+import { utils, eslint } from "@open-xchange/linter-presets"
+
+const resolve = utils.resolver(import.meta.url)
+
+export default [
+  ...eslint.configure({
+    ignores: ["dist/*", "external/**/*.yaml"],
+    language: { ecmaVersion: 2024, sourceType: "commonjs" },
+    license: resolve("./license.txt"),
+    stylistic: { quotes: "double", semi: true },
+  }),
+]
+```
+
+## Environment Presets
+
+Environment presets will be applied to specific subsets of the project. Usually, they import one or more external ESLint plugins, apply their recommended rule set, and add or modify a few of their rules to establish the default setup for the project. All environment presets allow to pass rule records to override the recommended rules.
+
+### Overview
+
+The names of the environment presets are linked to detailed descriptions.
+
+| Name | Description |
+| - | - |
+| [`env.tsconfig`](./env/tsconfig.md) | TypeScript project setup (per `tsconfig.json` file). |
+| [`env.node`](./env/node.md) | Modules running in NodeJS. |
+| [`env.browser`](./env/browser.md) | Modules running in browsers. |
+| [`env.react`](./env/react.md) | Modules using [React](https://react.dev/) library. |
+| [`env.jest`](./env/jest.md) | Unit tests with [Jest](https://jestjs.io/). |
+| [`env.vitest`](./env/vitest.md) | Unit tests with [Vitest](https://vitest.dev/). |
+| [`env.codecept`](./env/codecept.md) | E2E tests with [CodeceptJS](https://codecept.io/). |
+| [`env.eslint`](./env/eslint.md) | Implementation of custom ESLint rules. |
+| [`env.project`](./env/project.md) | Project setup and module imports. |

package/lib/eslint/config/base.js

@@ -120,7 +120,6 @@ export default function base(options) {
                 "no-useless-return": "error",
                 "no-var": "error",
                 "object-shorthand": "error",
-                "one-var": ["error", "never"],
                 "operator-assignment": "error",
                 "prefer-arrow-callback": "error",
                 "prefer-const": ["error", { ignoreReadBeforeAssign: true }],

package/lib/eslint/config/imports.js

@@ -0,0 +1,68 @@
+
+import { fixupPluginRules } from "@eslint/compat";
+import importPlugin from "eslint-plugin-import";
+
+// exports ====================================================================
+
+/**
+ * Adds linter rules for `import` and `export` statements.
+ *
+ * Wraps the following packages:
+ * - `eslint-plugin-import`
+ *
+ * @param {Required<import("../shared/types").LanguageOptions>} options
+ *  Resolved configuration options.
+ *
+ * @returns {import("../shared/types.js").FlatConfigArray}
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function importConfig(options) {
+
+    // configuration properties
+    const { ecmaVersion, sourceType } = options;
+
+    // extensions of ES module files
+    const jsExtensions = (sourceType === "module") ? [".js", ".mjs"] : [".mjs"];
+    const tsExtensions = (sourceType === "module") ? [".ts", ".mts"] : [".mts"];
+
+    return [{
+        files: [
+            ...jsExtensions.map(ext => "**/*" + ext),
+            ...tsExtensions.map(ext => "**/*" + ext),
+        ],
+
+        // register rule implementations of the plugin
+        plugins: {
+            import: fixupPluginRules(importPlugin), // https://github.com/import-js/eslint-plugin-import/issues/2948
+        },
+
+        // language options need to be repeated for this plugin
+        languageOptions: {
+            parserOptions: {
+                ecmaVersion,
+                sourceType: "module",
+            },
+        },
+
+        // parser settings need to be repeated for this plugin
+        settings: {
+            "import/parsers": {
+                espree: jsExtensions,
+                "@typescript-eslint/parser": tsExtensions,
+            },
+        },
+
+        // reconfigure plugin rules
+        rules: {
+            // recommended rules
+            ...importPlugin.configs.recommended.rules,
+            ...importPlugin.configs.typescript.rules,
+            // change or disable a few recommended rules
+            "import/default": "off",
+            "import/no-duplicates": "error",
+            "import/no-named-as-default": "off",
+            "import/no-named-as-default-member": "off",
+            "import/no-unresolved": "off",
+        },
+    }];
+}

package/lib/eslint/config/js.js

@@ -1,5 +1,5 @@
 
-import { NO_UNUSED_VARS_OPTIONS } from "../shared/constants.js";
+import { NO_UNUSED_VARS_OPTIONS } from "../shared/env-utils.js";
 
 // functions ==================================================================
 

package/lib/eslint/config/ts.js

@@ -7,7 +7,7 @@
 
 import typescriptEslint from "typescript-eslint";
 
-import { NO_UNUSED_VARS_OPTIONS } from "../shared/constants.js";
+import { NO_UNUSED_VARS_OPTIONS } from "../shared/env-utils.js";
 
 // functions ==================================================================
 

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

@@ -1,12 +1,20 @@
 
-import { FlatConfigArray, EnvBaseOptions } from "../shared/types.js";
+import { FlatConfigArray } from "../shared/types";
+import { EnvBaseOptions, EnvRestrictedOptions } from "../shared/env-utils";
 
 // types ======================================================================
 
 /**
  * Configuration options for the environment preset "env.browser".
  */
-export interface EnvBrowserOptions extends EnvBaseOptions { }
+export interface EnvBrowserOptions extends EnvBaseOptions {
+
+    /**
+     * All globals, imports, properties, and syntax constructs to be banned for
+     * the files included by the environment.
+     */
+    restricted?: EnvRestrictedOptions;
+}
 
 // functions ==================================================================
 

package/lib/eslint/env/browser.js

@@ -2,7 +2,7 @@
 import JAVASCRIPT_GLOBALS from "globals";
 import CONFUSING_BROWSER_GLOBALS from "confusing-browser-globals";
 
-import { RESTRICTED_GLOBALS, RESTRICTED_SYNTAX } from "../shared/constants.js";
+import { generateRestrictedRules } from "../shared/env-utils.js";
 
 // constants ==================================================================
 
@@ -36,6 +36,21 @@ const AMBIGUOUS_BROWSER_TYPES = [
     "Transformer",
 ];
 
+/**
+ * Properties of global objects to be banned in all browser modules.
+ */
+const RESTRICTED_PROPERTIES = [
+    { object: "Object", property: "hasOwn", message: "Missing browser support." },
+];
+
+/**
+ * Syntax constructs to be banned in all browser modules.
+ */
+const RESTRICTED_SYNTAX = [
+    { selector: "ClassBody > StaticBlock", message: "Static blocks not supported yet." },
+    { selector: "ExportNamedDeclaration > TSEnumDeclaration[const=true]", message: "Do not export const enums." },
+];
+
 // initialization =============================================================
 
 /**
@@ -68,7 +83,7 @@ for (const name of CONFUSING_BROWSER_GLOBALS) {
 }
 
 // Create the configuration list for rule "no-restricted-globals".
-const AMBIGUOUS_BROWSER_GLOBALS = AMBIGUOUS_BROWSER_TYPES.map(name => {
+const RESTRICTED_GLOBALS = AMBIGUOUS_BROWSER_TYPES.map(name => {
     const message = `Import custom type '${name}', or use 'window.${name}' for disambiguation.`;
     return { name, message };
 });
@@ -94,34 +109,33 @@ 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,
+    // generate the "no-restricted-?" rules according to passed configuration
+    const restricted = generateRestrictedRules({
+        globals: RESTRICTED_GLOBALS,
+        properties: RESTRICTED_PROPERTIES,
+        syntax: RESTRICTED_SYNTAX,
+    }, options?.restricted);
+
+    return [
+
+        // base configuration for the environment
+        {
+            files,
+            ignores,
+
+            // register global symbols used in browser scripts
+            languageOptions: {
+                globals: BROWSER_GLOBALS,
+            },
+
+            // configure rules
+            rules: {
+                ...restricted.rules,
+                ...rules,
+            },
         },
 
-        // 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,
-        },
-    }];
+        // "no-restricted-?" rules overrides for specific files
+        ...restricted.overrides,
+    ];
 }

package/lib/eslint/env/browser.md

@@ -0,0 +1,33 @@
+# Environment `env.browser`
+
+Creates configuration objects with global symbols and linter rules for modules running in the browser. Adds well-known [browser globals](https://github.com/sindresorhus/globals), and forbids [confusing browser globals](https://github.com/facebook/create-react-app/tree/main/packages/confusing-browser-globals).
+
+## Signature
+
+```ts
+function browser(options: EnvBrowserOptions): Linter.FlatConfig[]
+```
+
+## Options
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `files` | `string[]` | _required_ | Glob patterns for source files to be included. |
+| `ignores` | `string[]` | `[]` | Glob patterns for source files matching `files` to be ignored. |
+| `restricted` | `EnvRestrictedOptions` | `{}` | Settings for banned globals, imports, object properties, and syntax constructs. |
+| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the configuration. |
+
+## Example
+
+```js
+// eslint.config.js
+import { eslint } from "@open-xchange/linter-presets"
+
+export default [
+  ...eslint.configure({ /* ... */ }),
+  ...eslint.env.browser({
+    files: ["src/**/*.{js,ts}"],
+    rules: { /* ... */ },
+  }),
+]
+```

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

@@ -1,5 +1,6 @@
 
-import { FlatConfigArray, EnvBaseOptions } from "../shared/types.js";
+import { FlatConfigArray } from "../shared/types";
+import { EnvBaseOptions } from "../shared/env-utils";
 
 // types ======================================================================
 

package/lib/eslint/env/codecept.md

@@ -0,0 +1,35 @@
+# Environment `env.codecept`
+
+Creates configuration objects with global symbols and linter rules for E2E tests using CodeceptJS. Adds the following plugins and their recommended rules:
+
+- [eslint-plugin-codeceptjs](https://github.com/poenneby/eslint-plugin-codeceptjs)
+- [eslint-plugin-chai-expect](https://github.com/turbo87/eslint-plugin-chai-expect)
+
+## Signature
+
+```ts
+function codecept(options: EnvCodeceptOptions): Linter.FlatConfig[]
+```
+
+## Options
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `files` | `string[]` | _required_ | Glob patterns for source files to be included. |
+| `ignores` | `string[]` | `[]` | Glob patterns for source files matching `files` to be ignored. |
+| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the configuration. |
+
+## Example
+
+```js
+// eslint.config.js
+import { eslint } from "@open-xchange/linter-presets"
+
+export default [
+  ...eslint.configure({ /* ... */ }),
+  ...eslint.env.codecept({
+    files: ["e2e/**/*.{js,ts}"],
+    rules: { /* ... */ },
+  }),
+]
+```

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

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

package/lib/eslint/env/eslint.js

@@ -0,0 +1,41 @@
+
+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("./eslint").EnvEslintOptions} 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 eslint(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/eslint.md

@@ -0,0 +1,32 @@
+# Environment `env.eslint`
+
+Creates configuration objects with linter rules for implementing custom ESlint plugins. Adds the plugin [eslint-plugin-eslint-plugin](https://github.com/eslint-community/eslint-plugin-eslint-plugin) and its recommended rules.
+
+## Signature
+
+```ts
+function plugin(options: EnvEslintOptions): Linter.FlatConfig[]
+```
+
+## Options
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `files` | `string[]` | _required_ | Glob patterns for source files to be included. |
+| `ignores` | `string[]` | `[]` | Glob patterns for source files matching `files` to be ignored. |
+| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the configuration. |
+
+## Example
+
+```js
+// eslint.config.js
+import { eslint } from "@open-xchange/linter-presets"
+
+export default [
+  ...eslint.configure({ /* ... */ }),
+  ...eslint.env.eslint({
+    files: ["eslint/rules/*.{js,ts}"],
+    rules: { /* ... */ },
+  }),
+]
+```

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

@@ -1,5 +1,6 @@
 
-import { FlatConfigArray, EnvBaseOptions } from "../shared/types.js";
+import { FlatConfigArray } from "../shared/types";
+import { EnvBaseOptions } from "../shared/env-utils";
 
 // types ======================================================================
 

package/lib/eslint/env/jest.md

@@ -0,0 +1,32 @@
+# Environment `env.jest`
+
+Creates configuration objects with global symbols and linter rules for unit tests using Jest. Adds the plugin [eslint-plugin-jest](https://github.com/jest-community/eslint-plugin-jest) and its recommended rules.
+
+## Signature
+
+```ts
+function jest(options: EnvJestOptions): Linter.FlatConfig[]
+```
+
+## Options
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `files` | `string[]` | _required_ | Glob patterns for source files to be included. |
+| `ignores` | `string[]` | `[]` | Glob patterns for source files matching `files` to be ignored. |
+| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the configuration. |
+
+## Example
+
+```js
+// eslint.config.js
+import { eslint } from "@open-xchange/linter-presets"
+
+export default [
+  ...eslint.configure({ /* ... */ }),
+  ...eslint.env.jest({
+    files: ["test/**/*.{js,ts}"],
+    rules: { /* ... */ },
+  }),
+]
+```

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

@@ -1,5 +1,6 @@
 
-import { FlatConfigArray, LanguageOptions, EnvBaseOptions } from "../shared/types.js";
+import { FlatConfigArray, LanguageOptions } from "../shared/types";
+import { EnvBaseOptions, EnvRestrictedOptions } from "../shared/env-utils";
 
 // types ======================================================================
 
@@ -14,6 +15,12 @@ export interface EnvNodeOptions extends EnvBaseOptions {
      * Default value is "module".
      */
     sourceType?: LanguageOptions["sourceType"];
+
+    /**
+     * All globals, imports, properties, and syntax constructs to be banned for
+     * the files included by the environment.
+     */
+    restricted?: EnvRestrictedOptions;
 }
 
 // functions ==================================================================

package/lib/eslint/env/node.js

@@ -3,7 +3,7 @@
 // - https://github.com/mysticatea/eslint-plugin-node/issues/341
 import nodePlugin from "eslint-plugin-n";
 
-import { RESTRICTED_GLOBALS, RESTRICTED_SYNTAX } from "../shared/constants.js";
+import { generateRestrictedRules } from "../shared/env-utils.js";
 
 // functions ==================================================================
 
@@ -28,17 +28,19 @@ export default function node(options) {
     const configKey = (sourceType === "commonjs") ? "flat/recommended-script" : "flat/recommended-module";
     const nodeConfig = nodePlugin.configs[configKey];
 
+    // generate the "no-restricted-?" rules according to passed configuration
+    const restricted = generateRestrictedRules({}, options?.restricted);
+
     return [
 
-        // register rule implementations and global symbols
+        // register rule implementations
         {
             files,
             ignores,
             ...nodeConfig,
-            // automatically add missing extensions in imports of CommonJS scripts
             settings: {
                 node: {
-                    tryExtensions: [".js", ".ts"],
+                    tryExtensions: [".js", ".ts", ".d.ts"], // automatically add missing extensions in imports
                 },
             },
         },
@@ -48,12 +50,14 @@ export default function node(options) {
             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",
+                ...restricted.rules,
                 ...rules,
             },
         },
+
+        // "no-restricted-?" rules overrides for specific files
+        ...restricted.overrides,
     ];
 }