@open-xchange/linter-presets 0.0.4 → 0.0.5

package/CHANGELOG.md

@@ -18,8 +18,13 @@
 - 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
+- chore: bump dependencies
 
 ## [0.0.4] - 2024-07-10
 
 - fixed: [ESLint] file exists detection in rule `env-project/no-invalid-modules`
+
+## [0.0.5] - 2024-07-10
+
+- chore: [ESLint] documentation for option `restricted`
+- chore: bump dependencies

package/lib/eslint/env/browser.md

@@ -14,9 +14,26 @@ function browser(options: EnvBrowserOptions): Linter.FlatConfig[]
 | - | - | - | - |
 | `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. |
+| `restricted` | `EnvRestrictedOptions` | `{}` | Settings for banned globals, imports, object properties, and syntax constructs (see below). |
 | `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the configuration. |
 
+### Option `restricted`
+
+- Type: `EnvRestrictedOptions`
+- Default: `{}`
+
+This option allows to specify banned globals, imports, object properties, and syntax constructs. These restricted items will be set on top of the built-in restricted items of the environment preset, and will be passed to the ESLint core rules [`no-restricted-globals`](https://eslint.org/docs/latest/rules/no-restricted-globals), [`no-restricted-imports`](https://eslint.org/docs/latest/rules/no-restricted-imports), [`no-restricted-properties`](https://eslint.org/docs/latest/rules/no-restricted-properties), and [`no-restricted-syntax`](https://eslint.org/docs/latest/rules/no-restricted-syntax), respectively.
+
+The option `restricted` is an object with the following properties:
+
+| Name | Type | Default | Description |
+| - | - | - | - |
+| `globals` | `EnvRestrictedName[]` | `[]` | Banned global symbols. Each entry is an object with string properties `name` and `message`. |
+| `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`. |
+| `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. |
+
 ## Example
 
 ```js
@@ -27,6 +44,28 @@ export default [
   ...eslint.configure({ /* ... */ }),
   ...eslint.env.browser({
     files: ["src/**/*.{js,ts}"],
+    restricted: {
+      globals: [
+        { name: "$", message: "Explicitly import the 'jquery' package." },
+      ],
+      imports: [
+        { name: "underscore", message: "Use the 'lodash' package." },
+      ],
+      properties: [
+        { object: "_", property: "flatten", message: "Use native 'Array::flat' instead." },
+      ],
+      syntax: [
+        { selector: "ClassBody > StaticBlock", message: "Static blocks not supported in all browsers." },
+      ],
+      overrides: [
+        {
+          files: "src/**/*.ts",
+          properties: [
+            { object: "$", property: "Deferred", message: "Use native promises in TypeScript code." },
+          ],
+        },
+      ],
+    },
     rules: { /* ... */ },
   }),
 ]

package/lib/eslint/env/node.md

@@ -15,9 +15,16 @@ function node(options: EnvNodeOptions): Linter.FlatConfig[]
 | `files` | `string[]` | _required_ | Glob patterns for source files to be included. |
 | `ignores` | `string[]` | `[]` | Glob patterns for source files matching `files` to be ignored. |
 | `sourceType` | `"module"\|"commonjs"` | `"module"` | Specifies how to treat `.js`, `.jsx`, `.ts`, and `.tsx`. |
-| `restricted` | `EnvRestrictedOptions` | `{}` | Settings for banned globals, imports, object properties, and syntax constructs. |
+| `restricted` | `EnvRestrictedOptions` | `{}` | Settings for banned globals, imports, object properties, and syntax constructs (see below). |
 | `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the configuration. |
 
+### Option `restricted`
+
+- Type: `EnvRestrictedOptions`
+- Default: `{}`
+
+This option allows to specify banned globals, imports, object properties, and syntax constructs. See [documentation in `env.browser`](./browser.md#option-restricted) for a detailed description.
+
 ## Example
 
 ```js

package/lib/eslint/env/project.md

@@ -90,7 +90,7 @@ Each key in the `packages` record is the arbitrary unique name of a package. The
 | Name | Type | Default | Description |
 | - | - | - | - |
 | `src` | `string\|string[]` | _required_ | Glob patterns selecting all source files that are part of the package. |
-| `dependsOn` | `string\|string[]` | `[]` | Specifies the names of all packages (dictionary keys of the option `packages`) this package depends on. |
+| `extends` | `string\|string[]` | `[]` | Specifies the names of all packages (dictionary keys of the option `packages`) this package depends on. |
 | `optional` | `boolean` | `false` | Set to `true` to mark an optional package that may be missing in an installation. Such a package cannot be imported statically (with `import` statement) from a non-optional package, but can only be loaded dynamically at runtime (by calling `import()`). The rule will mark all static imports of optional code as an error. |
 
 Modules that are part of such a package may import any modules from the same package, or from packages it depends on (also recursively from their dependent packages).
@@ -112,12 +112,12 @@ export default [
       },
       debug: {
         src: "@/debug/**/*",
-        dependsOn: "base",
+        extends: "base",
         optional: true,
       },
       special: {
         src: "@/my/special/**/*",
-        dependsOn: ["base", "debug"],
+        extends: ["base", "debug"],
       },
     },
   }),

package/lib/eslint/rules/no-invalid-modules.js

@@ -44,7 +44,7 @@ export default {
                 external: Schema.maybeArray(Schema.stringNE()),
                 packages: Schema.dictionary(Schema.options({
                     src: Schema.maybeArray(Schema.stringNE()),
-                    dependsOn: Schema.maybeArray(Schema.stringNE()),
+                    extends: Schema.maybeArray(Schema.stringNE()),
                     optional: Schema.boolean(),
                 }, ["src"])),
             }),
@@ -69,16 +69,19 @@ export default {
         // convert "alias" option to map
         const aliasMap = new Map(Object.entries(alias));
 
-        // convert "packages" option (strings to arrays)
+        // convert "packages" options (strings to arrays)
         const packagesMap = new Map();
-        const packagesGlobs = [];
         for (const [key, settings] of Object.entries(packages)) {
-            const { src, dependsOn, ...rest } = settings;
-            const srcGlobs = makeArray(src);
-            packagesMap.set(key, { src: srcGlobs, dependsOn: makeArray(dependsOn), ...rest });
-            packagesGlobs.push(...srcGlobs);
+            packagesMap.set(key, {
+                ...settings,
+                src: makeArray(settings.src),
+                extends: makeArray(settings.extends),
+            });
         }
 
+        // collect all globs for package members
+        const packagesGlobs = Array.from(packagesMap, settings => settings.src).flat();
+
         // resolve file name
         const packagePath = packageUpSync();
         const rootDir = toPosixPath(dirname(packagePath));
@@ -176,12 +179,12 @@ export default {
                     }
 
                     // do not traverse into dependencies of optional modules
-                    if ((settings.dependsOn.length === 0) || (!root && settings.optional)) {
+                    if (!settings.extends.length || (!root && settings.optional)) {
                         return false;
                     }
 
                     // allow imports from any of the dependent packages
-                    return settings.dependsOn.some(key => checkDependencies(packagesMap.get(key), false));
+                    return settings.extends.some(key => checkDependencies(packagesMap.get(key), false));
                 };
 
                 // check dependencies of all configured packages (not for anonymous modules)

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

@@ -80,9 +80,7 @@ export interface EnvRestrictedItems {
  * Collection of banned globals, imports, properties, and syntax constructs,
  * for a specific subset of the files included in an environment.
  */
-export interface EnvRestrictedOverride extends EnvFilesOptions, EnvRestrictedItems {
-    merge?: boolean;
-}
+export interface EnvRestrictedOverride extends EnvFilesOptions, EnvRestrictedItems { }
 
 /**
  * Configuration options for restricted imports and globals.

package/lib/eslint/shared/env-utils.js

@@ -33,17 +33,17 @@ export const NO_UNUSED_VARS_OPTIONS = {
 // functions ==================================================================
 
 /**
- * Concatenates the elements of multiple arrays. Skips all falsy parameters.
+ * Concatenates the elements of multiple arrays. Skips all nullish parameters.
  *
  * @template T
  *
- * @param {Array<T[] | undefined | null | false>} arrays
+ * @param {Array<T[] | undefined | null>} arrays
  *  The arrays to be concatenated.
  *
  * @returns {T[]}
  *  The concatenated arrays.
  */
-function flatten(...arrays) {
+function concatArrays(...arrays) {
     return arrays.flatMap(array => array || []);
 }
 
@@ -63,6 +63,10 @@ function createRulesRecord(generator) {
         const items = generator(key);
         if (items?.length) { rules[`no-restricted-${key}`] = ["error", ...items]; }
     }
+    // same restrictions for CommonJS `require` as for `import` statements
+    if ("no-restricted-imports" in rules) {
+        rules["no-restricted-modules"] = rules["no-restricted-imports"];
+    }
     return rules;
 }
 
@@ -82,22 +86,22 @@ export function generateRestrictedRules(fixed, options) {
 
     // restricted items for all files in the environment
     const items = {
-        globals: flatten(RESTRICTED_GLOBALS, fixed.globals, options?.globals),
-        imports: flatten(fixed.imports, options?.imports),
-        properties: flatten(fixed.properties, options?.properties),
-        syntax: flatten(RESTRICTED_SYNTAX, fixed.syntax, options?.syntax),
+        globals: concatArrays(RESTRICTED_GLOBALS, fixed.globals, options?.globals),
+        imports: concatArrays(fixed.imports, options?.imports),
+        properties: concatArrays(fixed.properties, options?.properties),
+        syntax: concatArrays(RESTRICTED_SYNTAX, fixed.syntax, options?.syntax),
     };
 
     // base rules for all files in the environment
     const rules = createRulesRecord(key => items[key]);
 
-    // generate the override entries (join with base items if specified)
+    // generate the override entries (join with base items)
     const overrides = [];
     for (const override of options?.overrides ?? []) {
         overrides.push({
             files: override.files,
             ignores: override.ignores ?? [],
-            rules: createRulesRecord(key => flatten(override.join && items[key], override[key])),
+            rules: createRulesRecord(key => concatArrays(items[key], override[key])),
         });
     }
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@open-xchange/linter-presets",
-    "version": "0.0.4",
+    "version": "0.0.5",
     "description": "Configuration presets for ESLint and StyleLint",
     "repository": "https://gitlab.open-xchange.com/fspd/npm-packages/linter-presets",
     "license": "MIT",
@@ -32,7 +32,7 @@
         "eslint-plugin-import": "2.29.1",
         "eslint-plugin-jest": "28.6.0",
         "eslint-plugin-jest-dom": "5.4.0",
-        "eslint-plugin-jsdoc": "48.5.2",
+        "eslint-plugin-jsdoc": "48.6.0",
         "eslint-plugin-jsonc": "2.16.0",
         "eslint-plugin-jsx-a11y": "6.9.0",
         "eslint-plugin-jsx-expressions": "1.3.2",
@@ -42,7 +42,7 @@
         "eslint-plugin-react": "7.34.3",
         "eslint-plugin-react-hooks": "4.6.2",
         "eslint-plugin-react-hooks-static-deps": "1.0.7",
-        "eslint-plugin-react-refresh": "0.4.7",
+        "eslint-plugin-react-refresh": "0.4.8",
         "eslint-plugin-testing-library": "6.2.2",
         "eslint-plugin-vitest": "0.5.4",
         "eslint-plugin-yml": "1.14.0",