@open-xchange/linter-presets 0.0.2 → 0.0.3

package/lib/eslint/env/node.md

@@ -0,0 +1,34 @@
+# Environment `env.node`
+
+Creates configuration objects with global symbols and linter rules for NodeJS modules. Adds the plugin [eslint-plugin-n](https://github.com/eslint-community/eslint-plugin-n) and its recommended rules.
+
+## Signature
+
+```ts
+function node(options: EnvNodeOptions): 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. |
+| `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. |
+| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the configuration. |
+
+## Example
+
+```js
+// eslint.config.js
+import { utils, eslint } from "@open-xchange/linter-presets"
+
+export default [
+  ...eslint.configure({ /* ... */ }),
+  ...eslint.env.node({
+    files: ["*.config.{js,ts}", "scripts/**/*.js"],
+    rules: { /* ... */ },
+  }),
+]
+```

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

@@ -0,0 +1,21 @@
+
+import { FlatConfigArray } from "../shared/types";
+import { EnvBaseOptions } from "../shared/env-utils";
+
+// types ======================================================================
+
+/**
+ * Configuration options for the environment preset "env.project".
+ */
+export interface EnvProjectOptions extends EnvBaseOptions {
+
+    /**
+     * Maps all alias prefixes to actual paths in the project. All paths must
+     * be relative to the project's root directory.
+     */
+    alias?: Record<string, string>;
+}
+
+// functions ==================================================================
+
+export default function project(options: EnvProjectOptions): FlatConfigArray;

package/lib/eslint/env/{plugin.js → project.js}

@@ -19,43 +19,44 @@
  *
  */
 
-import eslintPlugin from "eslint-plugin-eslint-plugin";
+import noAmdModuleDirective from "../rules/no-amd-module-directive.js";
+import noInvalidModules from "../rules/no-invalid-modules.js";
 
 // exports ====================================================================
 
 /**
- * Adds linter rules for ESLint plugin implementations.
+ * Adds custom linter rules for checking project setup and module hierarchy.
  *
- * Wraps the following packages:
- * - `eslint-plugin-eslint-plugin`
- *
- * @param {import("./plugin").EnvPluginOptions} options
+ * @param {import("./project").EnvProjectOptions} 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) {
+export default function project(options) {
 
     // configuration properties
-    const { files, ignores = [], rules = {} } = options;
-    // the plugin configuration
-    const pluginConfig = eslintPlugin.configs["flat/rules-recommended"];
+    const { files, ignores = [], rules, ...rest } = options;
 
-    return [
+    return [{
+        files,
+        ignores,
 
-        // register rule implementations and recommended rules
-        {
-            files,
-            ignores,
-            ...pluginConfig,
+        // register rule implementations
+        plugins: {
+            "env-project": {
+                rules: {
+                    "no-amd-module-directive": noAmdModuleDirective,
+                    "no-invalid-modules": noInvalidModules,
+                },
+            },
         },
 
-        // reconfigure plugin rules
-        {
-            files,
-            ignores,
-            rules,
+        // configure rules
+        rules: {
+            "env-project/no-amd-module-directive": "error",
+            "env-project/no-invalid-modules": ["error", rest],
+            ...rules,
         },
-    ];
+    }];
 }

package/lib/eslint/env/project.md

@@ -0,0 +1,129 @@
+# Environment `env.project`
+
+Creates configuration objects for custom project setup and module imports.
+
+- Source files will be checked for the correct usage of ES modules with static `import` and `export` statements, as well as dynamic `import` expressions. For the latter, only literal strings will be checked, other expressions that build the imported module names dynamically cannot be checked.
+
+- Enforces an hierarchy of internal packages. If a project distributes its source files into multiple installation packages, the dependencies between these packages can be checked to prevent that files from a base package import files from a dependent package (which may not get installed on the target machine).
+
+- Bans the TypeScript compiler directive `<amd-module>`. This directive was used in the past to declare module names when transpiling TypeScript module code to AMD modules.
+
+## Signature
+
+```ts
+function project(options: EnvProjectOptions): 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. |
+| `alias` | `Record<string, string>` | `{}` | Maps all alias prefixes to actual paths in the project (see below). |
+| `external` | `string \| string[]` | `[]` | Specifies glob patterns for external modules (see below). |
+| `packages` | `Record<string, EnvProjectPackage>` | `{}` | Allows to separate the source files into virtual packages (see below). |
+| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the configuration. |
+
+### Option `alias`
+
+- Type: `Record<string, string>`
+- Default: `{}`
+
+Maps all alias prefixes to actual paths in the project. All paths must be relative to the project's root directory.
+
+#### `alias` Example
+
+```js
+// eslint.config.js
+import { eslint } from "@open-xchange/linter-presets"
+
+export default [
+  ...eslint.configure({ /* ... */ }),
+  ...eslint.env.project({
+    files: ["src/**/*.{js,ts}"],
+    alias: {
+        "@": "src",
+    },
+  }),
+]
+```
+
+- The alias prefix `"@/"` of a module name will be replaced with the path `src/` to check the existence of source files.
+- The module `"@/my/module"` will correspond to the file `src/my/module.js` (relative to the project's root directory).
+
+### Option `external`
+
+- Type: `string | string[]`
+- Default: `[]`
+
+Specifies glob patterns for modules that can be imported although there is no module file available, e.g. due to build tool configuration.
+
+#### `external` Example
+
+```js
+// eslint.config.js
+import { eslint } from "@open-xchange/linter-presets"
+
+export default [
+  ...eslint.configure({ /* ... */ }),
+  ...eslint.env.project({
+    files: ["src/**/*.{js,ts}"],
+    alias: { "@": "src" },
+    external: ["virtual:*", "@/special/lib/**/*.js"],
+  }),
+]
+```
+
+- All imports starting with `"virtual:"` will not be checked.
+- All imports of `.js` files deeply inside `src/special/lib/` will not be checked.
+
+### Option `packages`
+
+- Type: `Record<string, EnvProjectPackage>`
+- Default: `{}`
+
+Allows to separate the source files into several virtual packages. This option is completely independent from any actual packaging performed in later steps of the build process. Its solely purpose is to impose dependencies between the source files to prevent importing files between specific packages.
+
+Each key in the `packages` record is the arbitrary unique name of a package. The record values must be objects satisfying the interface `EnvProjectPackage`:
+
+| 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. |
+| `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).
+
+Example configuration:
+
+```js
+// eslint.config.js
+import { eslint } from "@open-xchange/linter-presets"
+
+export default [
+  ...eslint.configure({ /* ... */ }),
+  ...eslint.env.project({
+    files: ["src/**/*.{js,ts}"],
+    alias: { "@": "src" },
+    packages: {
+      base: {
+        src: ["@/base/**/*", "@/tools/**/*"],
+      },
+      debug: {
+        src: "@/debug/**/*",
+        dependsOn: "base",
+        optional: true,
+      },
+      special: {
+        src: "@/my/special/**/*",
+        dependsOn: ["base", "debug"],
+      },
+    },
+  }),
+]
+```
+
+- The package `base` contains all modules starting with `@/base/` or `@/tools/`. All modules in the package `base` can import themselves, but they cannot import any other modules from the project.
+- The _optional_ package `debug` contains all modules starting with `@/debug/`. Modules in this package can import other modules from this package, and from the package `base`. Modules in this package can only be imported dynamically from other packages.
+- The package `special` contains all modules starting with `@/my/special/`. Modules in this package can import other modules from this package, and all modules from the packages `base` and `debug`. The latter package can only be imported dynamically.

package/lib/eslint/env/react.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/react.md

@@ -0,0 +1,39 @@
+# Environment `env.react`
+
+Creates configuration objects with linter rules for ReactJS. Adds the following plugins and their recommended rules:
+
+- [eslint-plugin-react](https://github.com/jsx-eslint/eslint-plugin-react)
+- [eslint-plugin-react-hooks](https://github.com/facebook/react/tree/main/packages/eslint-plugin-react-hooks)
+- [eslint-plugin-react-hooks-static-deps](https://github.com/stoikio/eslint-plugin-react-hooks-static-deps)
+- [eslint-plugin-react-refresh](https://github.com/ArnaudBarre/eslint-plugin-react-refresh)
+- [eslint-plugin-jsx-expressions](https://github.com/hluisson/eslint-plugin-jsx-expressions)
+- [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)
+
+## Signature
+
+```ts
+function react(options: EnvReactOptions): 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.react({
+    files: ["src/**/*.{js,ts}"],
+    rules: { /* ... */ },
+  }),
+]
+```

package/lib/eslint/env/tsconfig.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/tsconfig.js

@@ -28,8 +28,6 @@ export default function tsconfig(options) {
 
         // configure plugin rules
         rules: {
-            // imports will be checked by TSC
-            "n/no-missing-import": "off",
             // custom rules
             ...rules,
         },

package/lib/eslint/env/tsconfig.md

@@ -0,0 +1,35 @@
+# Environment `env.tsconfig`
+
+Creates configuration objects for TypeScript projects (registers a `tsconfig.json` file in the project).
+
+## Signature
+
+```ts
+function tsconfig(options: EnvTSConfigOptions): 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. |
+| `project` | `string` | _required_ | The absolute path to the TypeScript project configuration file (`tsconfig.json`). |
+| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the configuration. |
+
+## Example
+
+```js
+// eslint.config.js
+import { utils, eslint } from "@open-xchange/linter-presets"
+
+const resolve = utils.resolver(import.meta.url)
+
+export default [
+  ...eslint.configure({ /* ... */ }),
+  ...eslint.env.tsconfig({
+    files: ["src/**/*.ts"],
+    project: resolve("src/tsconfig.json"),
+  }),
+]
+```

package/lib/eslint/env/vitest.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/vitest.md

@@ -0,0 +1,36 @@
+# Environment `env.vitest`
+
+Creates configuration objects with global symbols and linter rules for unit tests using Vitest. Adds the following plugins and their recommended rules:
+
+- [eslint-plugin-vitest](https://github.com/veritem/eslint-plugin-vitest)
+- [eslint-plugin-testing-library](https://github.com/testing-library/eslint-plugin-testing-library)
+- [eslint-plugin-jest-dom](https://github.com/testing-library/eslint-plugin-jest-dom)
+
+## Signature
+
+```ts
+function vitest(options: EnvVitestOptions): 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.vitest({
+    files: ["test/**/*.{js,ts}"],
+    rules: { /* ... */ },
+  }),
+]
+```

package/lib/eslint/index.d.ts

@@ -1,5 +1,5 @@
 
-import { FlatConfigArray, ESLintConfigureOptions } from "./shared/types";
+import { FlatConfigArray, ConfigureOptions } from "./shared/types";
 
 import tsconfig from "./env/tsconfig";
 import node from "./env/node";
@@ -8,7 +8,8 @@ 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";
+import project from "./env/project";
+import eslint from "./env/eslint";
 
 // environments ===============================================================
 
@@ -23,7 +24,8 @@ export const env: {
     vitest: typeof vitest;
     codecept: typeof codecept;
     react: typeof react;
-    plugin: typeof plugin;
+    project: typeof project;
+    eslint: typeof eslint;
 };
 
 // functions ==================================================================
@@ -38,4 +40,4 @@ export const env: {
  * @returns
  *  An array of configuration objects to be added to the flat configuration.
  */
-export function configure(options?: ESLintConfigureOptions): FlatConfigArray;
+export function configure(options?: ConfigureOptions): FlatConfigArray;

package/lib/eslint/index.js

@@ -6,6 +6,7 @@ import json from "./config/json.js";
 import yaml from "./config/yaml.js";
 import license from "./config/license.js";
 import directives from "./config/directives.js";
+import imports from "./config/imports.js";
 import promises from "./config/promises.js";
 import jsdoc from "./config/jsdoc.js";
 import stylistic from "./config/stylistic.js";
@@ -17,7 +18,8 @@ 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 plugin from "./env/plugin.js";
+import project from "./env/project.js";
+import eslint from "./env/eslint.js";
 
 // environment presets ========================================================
 
@@ -32,7 +34,8 @@ export const env = {
     vitest,
     codecept,
     react,
-    plugin,
+    project,
+    eslint,
 };
 
 // functions ==================================================================
@@ -41,7 +44,7 @@ export const env = {
  * Generates standard configuration objects targeting the source files in the
  * entire project.
  *
- * @param {import("./shared/types").ESLintConfigureOptions} [options]
+ * @param {import("./shared/types").ConfigureOptions} [options]
  *  Plugin configuration options.
  *
  * @returns {import("./shared/types").FlatConfigArray}
@@ -91,6 +94,9 @@ export function configure(options) {
         // default configuration for ESLint inline directives
         ...directives(),
 
+        // default configuration for imports/exports
+        ...imports(languageOptions),
+
         // default configuration for native promises
         ...promises(),
 

package/lib/eslint/rules/no-amd-module-directive.js

@@ -0,0 +1,57 @@
+/*
+ * @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.
+ *
+ */
+
+// exports ====================================================================
+
+/** @type {import("eslint").Rule.RuleModule} */
+export default {
+
+    meta: {
+        type: "problem",
+        schema: [],
+        messages: {
+            UNEXPECTED_DIRECTIVE: "Unexpected '<amd-module>' directive.",
+            UNEXPECTED_DIRECTIVE_FIX: "Delete the '<amd-module>' directive.",
+        },
+        hasSuggestions: true,
+        fixable: "code",
+    },
+
+    create(context) {
+
+        return {
+
+            // fail if module contains triple-slash directive "<amd-module>"
+            Program(node) {
+                const amdComment = node.comments.find(comment => /^\/\s*<amd-module/.test(comment.value));
+                if (amdComment) {
+                    const deleteDirective = fixer => fixer.remove(amdComment);
+                    context.report({
+                        messageId: "UNEXPECTED_DIRECTIVE",
+                        node: amdComment,
+                        fix: deleteDirective,
+                        suggest: [{ messageId: "UNEXPECTED_DIRECTIVE_FIX", fix: deleteDirective }],
+                    });
+                }
+            },
+        };
+    },
+};