@open-xchange/linter-presets 1.6.0 → 1.7.0

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

@@ -1,4 +1,3 @@
-import { defineConfig } from "@eslint/config-helpers";
 import { flattenDeepArrays } from "../../utils/utils.js";
 // constants ==================================================================
 /**
@@ -67,22 +66,8 @@ export function extGlob(extensions) {
     return extensions.map(ext => "**/*." + ext);
 }
 /**
- * A version of ESLint's `defineConfig` that flattens multiple configuration
- * objects or deeply nested arrays into a flat array while skipping all falsy
- * parameters.
- *
- * @param configs
- *  The configuration objects to be flattened and filtered.
- *
- * @returns
- *  The flattened configuration array.
- */
-export function createConfigArray(...configs) {
-    return defineConfig(flattenDeepArrays(configs));
-}
-/**
- * Creates a flat configuration object with "files" and "ignores" settings from
- * an environment's "envOptions" object.
+ * Creates a configuration entry with "files" and "ignores" settings from an
+ * environment's "envOptions" object.
  *
  * @param name
  *  The name of the configuration entry.
@@ -90,28 +75,28 @@ export function createConfigArray(...configs) {
  * @param envOptions
  *  The environment options containing "files" and "ignores" settings.
  *
- * @param flatConfig
- *  Properties for the flat configuration to be built. Additional "files" and
+ * @param config
+ *  Properties for the configuration entry to be built. Additional "files" and
  *  "ignores" properties will be merged with the settings from "envOptions".
  *
  * @param rules
  *  Hard-coded rule settings to be added to the configuration.
  *
  * @returns
- *  The resulting flat configuration object.
+ *  The resulting configuration entry.
  */
-export function createConfig(name, envOptions, flatConfig, rules) {
+export function createConfig(name, envOptions, config, rules) {
     return {
         name,
-        ...flatConfig,
-        files: flattenDeepArrays(envOptions.files, flatConfig.files),
-        ignores: flattenDeepArrays(envOptions.ignores, flatConfig.ignores),
-        rules: { ...flatConfig.rules, ...rules },
+        ...config,
+        files: flattenDeepArrays(envOptions.files, config.files),
+        ignores: flattenDeepArrays(envOptions.ignores, config.ignores),
+        rules: { ...config.rules, ...rules },
     };
 }
 /**
- * Creates a flat configuration object with "files", "ignores", and "rules"
- * settings from an environment's "envOptions" object.
+ * Creates a configuration entry with "files", "ignores", and "rules" settings
+ * from an environment's "envOptions" object.
  *
  * @param name
  *  The name of the configuration entry.
@@ -126,7 +111,7 @@ export function createConfig(name, envOptions, flatConfig, rules) {
  *  allow to override them.
  *
  * @returns
- *  The resulting flat configuration object, if the environment options contain
+ *  The resulting configuration entry, if the environment options contain
  *  custom rule settings, otherwise `undefined`.
  */
 export function customRules(name, envOptions, rules) {
@@ -145,9 +130,10 @@ export function customRules(name, envOptions, rules) {
  * @returns
  *  The fixed configuration options.
  */
-export function fixMissingFilesOption(configs) {
-    const files = configs.find(config => !!config.files)?.files;
-    return files ? configs.map(config => (!config.files && (config.languageOptions || config.rules)) ? { ...config, files } : config) : configs;
+export function fixMissingFilesOption(...configs) {
+    const flatConfigs = flattenDeepArrays(configs);
+    const files = flatConfigs.find(config => !!config.files)?.files;
+    return files ? flatConfigs.map(config => (!config.files && (config.languageOptions || config.rules)) ? { ...config, files } : config) : flatConfigs;
 }
 /**
  * Converts all warnings in the passed rule options to errors.

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

@@ -1,5 +1,5 @@
 import type { Linter } from "eslint";
-import type { EnvFilesOptions, EnvBaseOptions } from "./env-utils.js";
+import type { ConfigWithExtendsArg, EnvFilesOptions, EnvBaseOptions } from "./env-utils.js";
 /**
  * Configuration for a single banned global or import.
  */
@@ -85,6 +85,6 @@ export declare function builtinRestrictedRules(): Linter.RulesRecord;
  *  The fixed restricted items provided by the environment preset.
  *
  * @returns
- *  The flat configuration objects needed to forbid the restricted items.
+ *  The configuration entries needed to forbid the restricted items.
  */
-export declare function restrictedRulesConfig(baseName: string, envOptions: EnvRestrictedOptions, fixed?: EnvRestrictedItems): Linter.Config[];
+export declare function restrictedRulesConfig(baseName: string, envOptions: EnvRestrictedOptions, fixed?: EnvRestrictedItems): ConfigWithExtendsArg;

package/dist/eslint/shared/restricted.js

@@ -1,5 +1,5 @@
 import { flattenDeepArrays } from "../../utils/utils.js";
-import { createConfigArray, createConfig } from "./env-utils.js";
+import { createConfig } from "./env-utils.js";
 // functions ==================================================================
 /**
  * Creates a rules record for all restricted items.
@@ -77,20 +77,21 @@ export function builtinRestrictedRules() {
  *  The fixed restricted items provided by the environment preset.
  *
  * @returns
- *  The flat configuration objects needed to forbid the restricted items.
+ *  The configuration entries needed to forbid the restricted items.
  */
 export function restrictedRulesConfig(baseName, envOptions, fixed) {
     const { restricted } = envOptions;
     // restricted items for all files in the environment
     const items = mergeRestrictedItems(fixed, restricted);
     // generate the configuration objects
-    return createConfigArray(
-    // base rules for all files in the environment
-    createConfig(baseName, envOptions, {
-        rules: createRulesRecord(key => items[key]),
-    }), 
-    // generate the override entries (join with base items)
-    restricted?.overrides?.map((override, index) => createConfig(`${baseName}-override-${index}`, override, {
-        rules: createRulesRecord(key => flattenDeepArrays(items[key], override[key])),
-    })));
+    return [
+        // base rules for all files in the environment
+        createConfig(baseName, envOptions, {
+            rules: createRulesRecord(key => items[key]),
+        }),
+        // generate the override entries (join with base items)
+        restricted?.overrides?.map((override, index) => createConfig(`${baseName}-override-${index}`, override, {
+            rules: createRulesRecord(key => flattenDeepArrays(items[key], override[key])),
+        })),
+    ];
 }

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

@@ -1,5 +1,4 @@
-import type { Linter } from "eslint";
-import { type EnvBaseOptions } from "./env-utils.js";
+import type { ConfigWithExtendsArg, EnvBaseOptions } from "./env-utils.js";
 /**
  * Shared options for environment presets for unit tests.
  */
@@ -27,7 +26,7 @@ export interface EnvUnitTestOptions extends EnvBaseOptions {
     testingLib?: "angular" | "dom" | "marko" | "react" | "vue";
 }
 /**
- * Conditionally creates flat configuration objects for the ESLint plugins
+ * Conditionally creates configuration entries for the ESLint plugins
  * `eslint-plugin-jest-dom` and `eslint-plugin-testing-library`.
  *
  * @param baseName
@@ -37,6 +36,6 @@ export interface EnvUnitTestOptions extends EnvBaseOptions {
  *  The configuration options for the unit test environment.
  *
  * @returns
- *  The resulting flat configuration objects.
+ *  The resulting configuration entries.
  */
-export declare function createUnitTestPluginConfigs(baseName: string, envOptions: EnvUnitTestOptions): Linter.Config[];
+export declare function createUnitTestPluginConfigs(baseName: string, envOptions: EnvUnitTestOptions): ConfigWithExtendsArg;

package/dist/eslint/shared/unittest.js

@@ -1,10 +1,10 @@
 import extendedPlugin from "eslint-plugin-jest-extended";
 import jestDomPlugin from "eslint-plugin-jest-dom";
 import testingLibraryPlugin from "eslint-plugin-testing-library";
-import { createConfigArray, createConfig } from "./env-utils.js";
+import { createConfig } from "./env-utils.js";
 // functions ==================================================================
 /**
- * Conditionally creates flat configuration objects for the ESLint plugins
+ * Conditionally creates configuration entries for the ESLint plugins
  * `eslint-plugin-jest-dom` and `eslint-plugin-testing-library`.
  *
  * @param baseName
@@ -14,24 +14,25 @@ import { createConfigArray, createConfig } from "./env-utils.js";
  *  The configuration options for the unit test environment.
  *
  * @returns
- *  The resulting flat configuration objects.
+ *  The resulting configuration entries.
  */
 export function createUnitTestPluginConfigs(baseName, envOptions) {
-    return createConfigArray(
-    // "jest-extended" plugin (config "flat/recommended" is empty)
-    envOptions.jestExtended && createConfig(`${baseName}:extended`, envOptions, extendedPlugin.configs["flat/all"]), 
-    // "jest-dom" plugin
-    envOptions.jestDom && createConfig(`${baseName}:jest-dom`, envOptions, jestDomPlugin.configs["flat/recommended"]), 
-    // "testing-library" plugin
-    envOptions.testingLib && createConfig(`${baseName}:testing-library`, envOptions, {
-        // register rule implementations of the plugins
-        plugins: {
-            "testing-library": testingLibraryPlugin,
-        },
-        // recommended rules
-        rules: {
-            ...testingLibraryPlugin.configs["flat/react"].rules,
-            "testing-library/no-node-access": ["error", { allowContainerFirstChild: true }],
-        },
-    }));
+    return [
+        // "jest-extended" plugin (config "flat/recommended" is empty)
+        envOptions.jestExtended && createConfig(`${baseName}:extended`, envOptions, extendedPlugin.configs["flat/all"]),
+        // "jest-dom" plugin
+        envOptions.jestDom && createConfig(`${baseName}:jest-dom`, envOptions, jestDomPlugin.configs["flat/recommended"]),
+        // "testing-library" plugin
+        envOptions.testingLib && createConfig(`${baseName}:testing-library`, envOptions, {
+            // register rule implementations of the plugins
+            plugins: {
+                "testing-library": testingLibraryPlugin,
+            },
+            // recommended rules
+            rules: {
+                ...testingLibraryPlugin.configs["flat/react"].rules,
+                "testing-library/no-node-access": ["error", { allowContainerFirstChild: true }],
+            },
+        }),
+    ];
 }

package/dist/stylelint/index.d.ts

@@ -1,5 +1,4 @@
 import type { Config } from "stylelint";
-export * from "../utils/resolver.js";
 /**
  * Configuration options for StyleLint code style rules.
  */
@@ -20,15 +19,19 @@ export interface StylisticOptions {
 /**
  * Configuration options for linting the entire project with StyleLint.
  */
-export interface ConfigureOptions {
+export interface ProjectOptions {
+    /**
+     * The URL of the project root containing the StyleLint configuration file.
+     * Should usually be set to `import.meta.url`.
+     */
+    root: string;
     /**
      * Glob patterns with all files and folders to be ignored by StyleLint.
      */
     ignores?: string[];
     /**
-     * Full path to the template file containing the license header to be used
-     * in all source files. The function `resolver` helps to to convert a local
-     * path to an absolute path.
+     * Path to the template file containing the license header to be used in
+     * all source files. May be a path relative to the project root.
      */
     license?: string;
     /**
@@ -50,4 +53,4 @@ export interface ConfigureOptions {
  * @returns
  *  The configuration object to be exported from `stylelint.config.js`.
  */
-export declare function defineConfig(options?: ConfigureOptions): Config;
+export declare function defineConfig(options: ProjectOptions): Config;

package/dist/stylelint/index.js

@@ -1,5 +1,4 @@
-// re-exports =================================================================
-export * from "../utils/resolver.js";
+import { PathResolver } from "../utils/resolver.js";
 // functions ==================================================================
 /**
  * Generates a StyleLint configuration object targeting the source files in the
@@ -18,16 +17,16 @@ export function defineConfig(options) {
         "coverage", // Vitest
         ".nuxt", // NuxtJS
         ".output", // NuxtJS
-        ...(options?.ignores ?? []),
+        ...(options.ignores ?? []),
     ];
     // resolve stylistic configuration options
     const stylistic = {
         indent: 4,
         quotes: "double",
-        ...options?.stylistic,
+        ...options.stylistic,
     };
     const rules = { base: {}, scss: {}, less: {} };
-    for (const [rule, value] of Object.entries(options?.rules ?? {})) {
+    for (const [rule, value] of Object.entries(options.rules ?? {})) {
         const key = rule.split("/")[0];
         (rules[key] ?? rules.base)[rule] = value;
     }
@@ -37,6 +36,8 @@ export function defineConfig(options) {
         "scss/double-slash-comment-empty-line-before": null,
         ...rules.scss,
     };
+    // the resolver for relative file paths
+    const resolver = new PathResolver(options.root);
     return {
         // ignore certain files and folders
         ignoreFiles,
@@ -73,7 +74,7 @@ export function defineConfig(options) {
             "rule-empty-line-before": null,
             "shorthand-property-no-redundant-values": [true, { ignore: ["four-into-three-edge-values"] }],
             // license-header plugin
-            ...(options?.license ? { "plugin/license-header": [true, { license: options.license }] } : null),
+            ...(options.license ? { "plugin/license-header": [true, { license: resolver.path(options.license) }] } : null),
             // stylistic plugin
             "@stylistic/declaration-colon-newline-after": null,
             "@stylistic/indentation": [stylistic.indent, { ignore: ["inside-parens"] }],

package/dist/utils/resolver.d.ts

@@ -1,12 +1,22 @@
-export type FileResolveFn = (file: string) => string;
 /**
- * Creates and returns a resolver function for file paths relative to the given
- * base URL of a script file.
- *
- * @param url
- *  The base URL of the calling script, usually `import.meta.url`.
- *
- * @returns
- *  A function that converts relative file paths to absolute file paths.
+ * A resolver for file paths relative to a base URL.
  */
-export declare function createResolver(url: string): FileResolveFn;
+export declare class PathResolver {
+    #private;
+    constructor(url: string);
+    /**
+     * @returns
+     *  The directory path of the URL passed to the constructor.
+     */
+    get root(): string;
+    /**
+     * Converts a file path relative to "root" to an absolute file path.
+     *
+     * @param file
+     *  The file path to be converted.
+     *
+     * @returns
+     *  The absolute file path.
+     */
+    path(file: string): string;
+}

package/dist/utils/resolver.js

@@ -1,15 +1,33 @@
+import { dirname } from "node:path";
 import { URL, fileURLToPath } from "node:url";
 // functions ==================================================================
 /**
- * Creates and returns a resolver function for file paths relative to the given
- * base URL of a script file.
- *
- * @param url
- *  The base URL of the calling script, usually `import.meta.url`.
- *
- * @returns
- *  A function that converts relative file paths to absolute file paths.
+ * A resolver for file paths relative to a base URL.
  */
-export function createResolver(url) {
-    return file => fileURLToPath(new URL(file, url));
+export class PathResolver {
+    #url;
+    #root;
+    constructor(url) {
+        this.#url = url;
+        this.#root = dirname(fileURLToPath(url));
+    }
+    /**
+     * @returns
+     *  The directory path of the URL passed to the constructor.
+     */
+    get root() {
+        return this.#root;
+    }
+    /**
+     * Converts a file path relative to "root" to an absolute file path.
+     *
+     * @param file
+     *  The file path to be converted.
+     *
+     * @returns
+     *  The absolute file path.
+     */
+    path(file) {
+        return fileURLToPath(new URL(file, this.#url));
+    }
 }

package/dist/utils/utils.d.ts

@@ -17,7 +17,7 @@ export type DeepOptArray<T> = T | false | null | undefined | ReadonlyArray<DeepO
  */
 export declare function yieldDeepArrays<T>(...arrays: Array<DeepOptArray<T>>): IterableIterator<T>;
 /**
- * Returns a flat array all truthy elements of all deeply nested arrays.
+ * Returns a flat array with all truthy elements of all deeply nested arrays.
  *
  * @template T
  *  The element type of the array.

package/dist/utils/utils.js

@@ -24,7 +24,7 @@ export function* yieldDeepArrays(...arrays) {
     }
 }
 /**
- * Returns a flat array all truthy elements of all deeply nested arrays.
+ * Returns a flat array with all truthy elements of all deeply nested arrays.
  *
  * @template T
  *  The element type of the array.

package/docs/eslint/README.md

@@ -4,31 +4,6 @@ The module `eslint` provides a `defineConfig` function to create a project-wide
 
 ## Functions
 
-### Function `createResolver`
-
-Creates and returns a function that will convert relative file paths to absolute file paths. Intended to be used with the base URL of the calling script, usually `import.meta.url`.
-
-#### `createResolver` Signature
-
-```ts
-function createResolver(url: string): (file: string) => string;
-```
-
-#### `createResolver` Example
-
-```js
-// eslint.config.ts
-import { createResolver, defineConfig } from "@open-xchange/linter-presets/eslint";
-
-const resolve = createResolver(import.meta.url);
-
-export default defineConfig({
-  // ...
-  license: resolve("./license.txt"),
-  // ...
-});
-```
-
 ### Function `defineConfig`
 
 Generates standard configuration targeting the source files in the entire project, and allows to add more custom configuration entries. Internally, various ESLint plugins will be included and configured to use their recommended rule sets.
@@ -53,7 +28,7 @@ Generates standard configuration targeting the source files in the entire projec
 #### `defineConfig` Signature
 
 ```ts
-function defineConfig(options: ConfigureOptions, ...configs: ConfigWithExtendsArg[]): Linter.Config[];
+function defineConfig(options: ProjectOptions, ...configs: ConfigWithExtendsArg[]): Linter.Config[];
 ```
 
 After the mandatory `options` parameters, the function can take multiple custom configuration objects or arrays, for example environment configuration presets (see below).
@@ -96,14 +71,12 @@ This package defines ignore globs for the following files and directories:
 
 ```ts
 // eslint.config.ts
-import { createResolver, defineConfig } from "@open-xchange/linter-presets/eslint";
-
-const resolve = createResolver(import.meta.url);
+import { defineConfig } from "@open-xchange/linter-presets/eslint";
 
 export default defineConfig({
   ignores: ["external/**/*.yaml"],
   language: { ecmaVersion: 2024, sourceType: "commonjs" },
-  license: resolve("./license.txt"),
+  license: "./license.txt",
   stylistic: { quotes: "single", semi: "never" },
 });
 ```

package/docs/stylelint/README.md

@@ -4,31 +4,6 @@ The module `stylelint` provides a `defineConfig` function for project-wide Style
 
 ## Functions
 
-### Function `createResolver`
-
-Creates and returns a function that will convert relative file paths to absolute file paths. Intended to be used with the base URL of the calling script, usually `import.meta.url`.
-
-#### `createResolver` Signature
-
-```ts
-function createResolver(url: string): (file: string) => string;
-```
-
-#### `createResolver` Example
-
-```js
-// stylelint.config.js
-import { createResolver, defineConfig } from "@open-xchange/linter-presets/stylelint";
-
-const resolve = createResolver(import.meta.url);
-
-export default defineConfig({
-  // ...
-  license: resolve("./license.txt"),
-  // ...
-});
-```
-
 ### Function `defineConfig`
 
 Generates standard configuration targeting the source files in the entire project. Internally, various StyleLint plugins will be included and configured to use their recommended rule sets.
@@ -45,7 +20,7 @@ Generates standard configuration targeting the source files in the entire projec
 ```ts
 import type { Config } from "stylelint";
 
-function defineConfig(options?: ConfigureOptions): Config;
+function defineConfig(options?: ProjectOptions): Config;
 ```
 
 #### `defineConfig` Options
@@ -72,13 +47,11 @@ This package defines ignore globs for the following files and directories:
 
 ```ts
 // stylelint.config.js
-import { createResolver, defineConfig } from "@open-xchange/linter-presets/stylelint";
-
-const resolve = createResolver(import.meta.url);
+import { defineConfig } from "@open-xchange/linter-presets/stylelint";
 
 export default defineConfig({
   ignores: ["external/**/*.scss"],
-  license: resolve("./license.txt"),
+  license: "./license.txt",
   stylistic: { indent: 2, quotes: "single" },
 });
 ```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-xchange/linter-presets",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Configuration presets for ESLint and StyleLint",
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
     "@eslint/config-helpers": "^0.3.0",
     "@eslint/js": "^9.31.0",
     "@eslint/markdown": "^7.0.0",
-    "@stylistic/eslint-plugin": "^5.1.0",
+    "@stylistic/eslint-plugin": "^5.2.0",
     "@stylistic/eslint-plugin-migrate": "^4.4.1",
     "@stylistic/stylelint-config": "^2.0.0",
     "@stylistic/stylelint-plugin": "^3.1.3",
@@ -53,7 +53,7 @@
     "eslint-plugin-jest": "^29.0.1",
     "eslint-plugin-jest-dom": "^5.5.0",
     "eslint-plugin-jest-extended": "^3.0.0",
-    "eslint-plugin-jsdoc": "^51.4.0",
+    "eslint-plugin-jsdoc": "^51.4.1",
     "eslint-plugin-jsonc": "^2.20.1",
     "eslint-plugin-jsx-a11y": "^6.10.2",
     "eslint-plugin-license-header": "^0.8.0",