@open-xchange/linter-presets 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## `1.2.0` – 2025-Jan-09
+
+- change: (ESLint) move support for native decorators in JS files into own environment `env.decorators`
+- removed: (ESLint) support for TypeScript's experimental decorators
+
 ## `1.1.1` – 2025-Jan-08
 
 - fix: (ESLint) remove obsolete package `eslint-import-resolver-typescript`

package/dist/eslint/config/base.js

@@ -1,6 +1,5 @@
 import eslintJs from "@eslint/js";
-import babelParser from "@babel/eslint-parser";
-import { JS_GLOB, SRC_GLOB, VUE_GLOB, extGlob } from "../shared/env-utils.js";
+import { SRC_GLOB, VUE_GLOB, extGlob } from "../shared/env-utils.js";
 import { builtinRestrictedRules } from "../shared/restricted.js";
 // functions ==================================================================
 /**
@@ -39,23 +38,6 @@ export default function base(languageConfig) {
         languageOptions("commonjs", "cjs", "cts"),
         // ECMA version and module type for *.js and *.ts files
         languageOptions(languageConfig.sourceType, "js", "jsx", "ts", "tsx"),
-        // ECMA decorators via Babel plugin
-        ...(languageConfig.nativeDecorators ? [{
-                files: JS_GLOB,
-                languageOptions: {
-                    parser: babelParser,
-                    parserOptions: {
-                        requireConfigFile: false,
-                        babelOptions: {
-                            babelrc: false,
-                            configFile: false,
-                            plugins: [
-                                ["@babel/plugin-proposal-decorators", { version: "2023-11" }],
-                            ],
-                        },
-                    },
-                },
-            }] : []),
         // configure linter rules
         {
             files: [...SRC_GLOB, ...VUE_GLOB],
@@ -129,7 +111,7 @@ export default function base(languageConfig) {
                 radix: "error",
                 "symbol-description": "error",
                 // built-in restricted items
-                ...builtinRestrictedRules(languageConfig),
+                ...builtinRestrictedRules(),
             },
         },
     ];

package/dist/eslint/env/decorators.d.ts

@@ -0,0 +1,21 @@
+import type { Linter } from "eslint";
+import type { EnvBaseOptions } from "../shared/env-utils.js";
+/**
+ * Configuration options for the environment preset "env.decorators".
+ */
+export interface EnvDecoratorsOptions extends EnvBaseOptions {
+}
+/**
+ * Adds support for native decorators in JavaScript source files.
+ *
+ * Wraps the following packages:
+ * - `@babel/eslint-parser`
+ * - `@babel/plugin-proposal-decorators`
+ *
+ * @param envOptions
+ *  Configuration options for the environment.
+ *
+ * @returns
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function decorators(envOptions: EnvBaseOptions): Linter.Config[];

package/dist/eslint/env/decorators.js

@@ -0,0 +1,34 @@
+import babelParser from "@babel/eslint-parser";
+import { TS_GLOB, concatConfigs, createConfig, customRules } from "../shared/env-utils.js";
+// functions ==================================================================
+/**
+ * Adds support for native decorators in JavaScript source files.
+ *
+ * Wraps the following packages:
+ * - `@babel/eslint-parser`
+ * - `@babel/plugin-proposal-decorators`
+ *
+ * @param envOptions
+ *  Configuration options for the environment.
+ *
+ * @returns
+ *  An array of configuration objects to be added to the flat configuration.
+ */
+export default function decorators(envOptions) {
+    return concatConfigs(createConfig(envOptions, {
+        ignores: TS_GLOB,
+        languageOptions: {
+            parser: babelParser,
+            parserOptions: {
+                requireConfigFile: false,
+                babelOptions: {
+                    babelrc: false,
+                    configFile: false,
+                    plugins: [
+                        ["@babel/plugin-proposal-decorators", { version: "2023-11" }],
+                    ],
+                },
+            },
+        },
+    }), customRules(envOptions));
+}

package/dist/eslint/index.d.ts

@@ -6,9 +6,10 @@ import jest from "./env/jest.js";
 import vitest from "./env/vitest.js";
 import codecept from "./env/codecept.js";
 import react from "./env/react.js";
-import project from "./env/project.js";
 import eslint from "./env/eslint.js";
+import project from "./env/project.js";
 import tsconfig from "./env/tsconfig.js";
+import decorators from "./env/decorators.js";
 /**
  * Configuration options for linting the entire project with ESLint.
  */
@@ -50,9 +51,10 @@ export declare const env: {
     vitest: typeof vitest;
     codecept: typeof codecept;
     react: typeof react;
-    project: typeof project;
     eslint: typeof eslint;
+    project: typeof project;
     tsconfig: typeof tsconfig;
+    decorators: typeof decorators;
 };
 /**
  * Generates ESLint configuration objects targeting the source files in the

package/dist/eslint/index.js

@@ -17,9 +17,10 @@ import jest from "./env/jest.js";
 import vitest from "./env/vitest.js";
 import codecept from "./env/codecept.js";
 import react from "./env/react.js";
-import project from "./env/project.js";
 import eslint from "./env/eslint.js";
+import project from "./env/project.js";
 import tsconfig from "./env/tsconfig.js";
+import decorators from "./env/decorators.js";
 // environment presets ========================================================
 /**
  * A collection with all available environment presets.
@@ -31,9 +32,10 @@ export const env = {
     vitest,
     codecept,
     react,
-    project,
     eslint,
+    project,
     tsconfig,
+    decorators,
 };
 // functions ==================================================================
 /**
@@ -59,7 +61,6 @@ export function configure(options) {
     const languageConfig = {
         ecmaVersion: "latest",
         sourceType: "module",
-        nativeDecorators: false,
         ...options?.language,
     };
     // resolve dependency configuration options

package/dist/eslint/shared/env-utils.d.ts

@@ -21,14 +21,6 @@ export interface LanguageOptions {
      * @default "module"
      */
     sourceType?: "module" | "commonjs";
-    /**
-     * Whether to support native ES decorators in JavaScript code (via Babel
-     * plugin). Does not affect TypeScript code which uses an own parser aware
-     * of the decorator syntax.
-     *
-     * @default false
-     */
-    nativeDecorators?: boolean;
 }
 export type LanguageConfig = DeepRequired<LanguageOptions>;
 /**

package/dist/eslint/shared/restricted.d.ts

@@ -1,5 +1,5 @@
 import type { Linter } from "eslint";
-import type { LanguageOptions, EnvFilesOptions, EnvBaseOptions } from "../shared/env-utils.js";
+import type { EnvFilesOptions, EnvBaseOptions } from "../shared/env-utils.js";
 /**
  * Configuration for a single banned global or import.
  */
@@ -46,15 +46,6 @@ export interface EnvRestrictedOverride extends EnvFilesOptions, EnvRestrictedIte
  * banned globals, imports, properties, and syntax constructs.
  */
 export interface EnvRestrictedOption extends EnvRestrictedItems {
-    /**
-     * Whether the environment supports native decorators. In this case, it
-     * will be required to replace TypeScript decorated `private` methods with
-     * native `#private` methods. TypeScript's experimental decorators cannot
-     * be used with native `#private` fields.
-     *
-     * @default false
-     */
-    nativeDecorators?: boolean;
     /**
      * Overrides for specific subsets of files in the environment. All
      * restricted items of overrides will be merged with the common restricted
@@ -76,13 +67,10 @@ export interface EnvRestrictedOptions extends EnvBaseOptions {
 /**
  * Creates restricted rules with built-in restricted items only.
  *
- * @param languageOptions
- *  The language options passed with the Linter configuration.
- *
  * @returns
  *  The rules dictionary with all needed restricted rules.
  */
-export declare function builtinRestrictedRules(languageOptions: LanguageOptions): Linter.RulesRecord;
+export declare function builtinRestrictedRules(): Linter.RulesRecord;
 /**
  * Generates various "no-restricted-?" rules from the passed configuration.
  *

package/dist/eslint/shared/restricted.js

@@ -27,22 +27,19 @@ function createRulesRecord(generator) {
 /**
  * Merges built-in items and custom items for restricted rules.
  *
- * @param nativeDecorators
- *  Whether to support native decorators in the code.
- *
  * @param restrictedItems
  *  The custom items for restricted rules to be merged.
  *
  * @returns
  *  The rules dictionary with all needed restricted rules.
  */
-function mergeRestrictedItems(nativeDecorators, ...restrictedItems) {
+function mergeRestrictedItems(...restrictedItems) {
     const RESTRICTED_GLOBALS = [
         { name: "isFinite", message: "Use 'Number.isFinite' instead." },
         { name: "isNaN", message: "Use 'Number.isNaN' instead." },
     ];
     const RESTRICTED_SYNTAX = [
-        { selector: ":matches(PropertyDefinition, MethodDefinition[kind!='constructor'])[accessibility='private']" + (nativeDecorators ? "" : "[decorators.length=0]"), message: "Use #private syntax instead." },
+        { selector: ":matches(PropertyDefinition, MethodDefinition[kind!='constructor'])[accessibility='private']", message: "Use #private syntax instead." },
     ];
     // restricted items for all files in the environment
     return {
@@ -56,15 +53,12 @@ function mergeRestrictedItems(nativeDecorators, ...restrictedItems) {
 /**
  * Creates restricted rules with built-in restricted items only.
  *
- * @param languageOptions
- *  The language options passed with the Linter configuration.
- *
  * @returns
  *  The rules dictionary with all needed restricted rules.
  */
-export function builtinRestrictedRules(languageOptions) {
+export function builtinRestrictedRules() {
     // built-in restricted items
-    const items = mergeRestrictedItems(!!languageOptions.nativeDecorators);
+    const items = mergeRestrictedItems();
     // generate the rules dictionary
     return createRulesRecord(key => items[key]);
 }
@@ -84,7 +78,7 @@ export function builtinRestrictedRules(languageOptions) {
 export function restrictedRulesConfig(envOptions, fixed) {
     const { restricted } = envOptions;
     // restricted items for all files in the environment
-    const items = mergeRestrictedItems(!!restricted?.nativeDecorators, fixed, restricted);
+    const items = mergeRestrictedItems(fixed, restricted);
     // generate the configuration objects
     return concatConfigs(
     // base rules for all files in the environment

package/doc/eslint/README.md

@@ -39,7 +39,6 @@ function configure(options?: ConfigureOptions): Linter.Config[]
 | `language` | `LanguageOptions` | | Configuration options for language and project setup. |
 | `language.ecmaVersion` | `number\|"latest"` | `latest` | 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. |
-| `language.nativeDecorators` | `boolean` | `false` | Whether to support native ES decorators in JavaScript code (via Babel plugin). Does not affect TypeScript code which uses an own parser aware of the decorator syntax. |
 | `packages` | `PackagesOptions` | | Configuration options for external package dependencies. |
 | `packages.allowed` | `string[]` | `[]` | Banned packages to be allowed in the project. |
 | `packages.banned` | `string[]` | `[]` | Additional packages to be banned in the project. |
@@ -101,3 +100,4 @@ The names of the environment presets are linked to detailed descriptions.
 | [`env.eslint`](./env/eslint.md) | Implementation of custom ESLint rules. |
 | [`env.project`](./env/project.md) | Project setup and module imports. |
 | [`env.tsconfig`](./env/tsconfig.md) | TypeScript project setup (per `tsconfig.json` file). Provided in case VSCode fails to use the new project service correctly. |
+| [`env.decorators`](./env/decorators.md) | Support for native decorators in JavaScript source files. |

package/doc/eslint/env/browser.md

@@ -32,7 +32,6 @@ The option `restricted` is an object with the following properties:
 | `imports` | `EnvRestrictedName[]` | `[]` | Banned modules that must not be imported. Each entry is an object with string properties `name` and `message`. |
 | `properties` | `EnvRestrictedProperty[]` | `[]` | Banned object properties. Each entry is an object with string properties `object`, `property`, and `message`). |
 | `syntax` | `EnvRestrictedSyntax[]` | `[]` | Banned syntax constructs by [AST selectors](https://eslint.org/docs/latest/extend/selectors). Each entry is an object with string properties `selector` and `message`. |
-| `nativeDecorators` | `boolean` | `false` | Whether the environment supports native decorators. In this case, it will be required to replace decorated TypeScript `private` methods with native `#private` methods (TypeScript's experimental decorators cannot be used with native `#private` fields). |
 | `overrides` | `EnvRestrictedOverride[]` | `[]` | Overrides for specific subsets of files in the environment. Each entry is an object with the common properties `files` (required) and `ignores`, and the properties `globals`, `imports`, `properties`, and `syntax` to specify restricted items (see above). All restricted items of overrides will be merged with the common restricted items defined for the entire environment. |
 
 The environment `env.browser` already defines the following built-in restrictions:

package/doc/eslint/env/decorators.md

@@ -0,0 +1,37 @@
+# Environment `env.decorators`
+
+Creates configuration objects to add support for native decorators to JavaScript source files.
+Does not affect TypeScript source files which use an own parser aware of the decorator syntax.
+
+Adds the following plugins:
+
+- [@babel/eslint-parser](https://www.npmjs.com/package/@babel/eslint-parser)
+- [@babel/plugin-proposal-decorators](https://babeljs.io/docs/babel-plugin-proposal-decorators)
+
+## Signature
+
+```ts
+function decorators(options: EnvDecoratorsOptions): Linter.Config[]
+```
+
+## 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.decorators({
+    files: ["src/**/*.js"],
+  }),
+]
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-xchange/linter-presets",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Configuration presets for ESLint and StyleLint",
   "repository": {
     "type": "git",