@open-xchange/linter-presets 0.0.6 → 0.1.0

package/{lib → dist}/eslint/shared/rule-utils.js

@@ -18,145 +18,112 @@
  * Any use of the work other than as authorized under this license or copyright law is prohibited.
  *
  */
-
 import { posix, sep } from "node:path";
 import { lstatSync } from "node:fs";
-
 import pm from "picomatch";
-
+import { AST_NODE_TYPES as NodeType } from "@typescript-eslint/utils";
 // Schema =====================================================================
-
 /**
  * Helper functions to build a JSON schema for custom ESLint rules.
  */
 export const Schema = {
-
     boolean() {
         return { type: "boolean" };
     },
-
-    string(options) {
-        return { type: "string", ...options };
+    string() {
+        return { type: "string" };
     },
-
-    stringNE(options) {
-        return Schema.string({ minLength: 1, ...options });
+    stringNE() {
+        return { type: "string", minLength: 1 };
     },
-
     array(items) {
         return { type: "array", items, uniqueItems: true };
     },
-
     maybeArray(items) {
         return { oneOf: [items, Schema.array(items)] };
     },
-
-    dictionary(items) {
-        return { type: "object", additionalProperties: items };
+    dictionary(properties) {
+        return { type: "object", additionalProperties: properties };
     },
-
     options(properties, required) {
         return { type: "object", properties, required, additionalProperties: false };
     },
 };
-
 // functions ==================================================================
-
 /**
- * Returns whether the passed value is nullish (either `undefined` or `null`).
+ * Returns a passed array unmodified, converts the value `undefined` to an
+ * empty array, and converts all other values to an array with one element.
  *
- * @param {unknown} value
- *  The value to be checked.
- *
- * @returns {boolean}
- *  Whether the passed value is nullish (either `undefined` or `null`).
- */
-export function isNullish(value) {
-    return (value === undefined) || (value === null);
-}
-
-/**
- * Returns a passed array unmodified, converts nullish values to an empty
- * array, and converts all other values to an array with one element.
- *
- * @param {unknown} value
+ * @param value
  *  Any value to be converted to an array.
  *
- * @returns {unknown[]}
+ * @returns
  *  An array containing the value, unless the value is already an array.
  */
 export function makeArray(value) {
-    return Array.isArray(value) ? value : isNullish(value) ? [] : [value];
+    return Array.isArray(value) ? value : (value === undefined) ? [] : [value];
 }
-
 /**
  * Converts a Windows file path to a Posix file path.
  *
- * @param {string} path
+ * @param path
  *  The file path to be normalized to Posix format.
  *
- * @returns {string}
+ * @returns
  *  The normalized Posix file path.
  */
 export function toPosixPath(path) {
     return path.replaceAll(sep, posix.sep);
 }
-
 /**
  * Returns whether the passed path refers to an existing file.
  *
- * @param {string} path
+ * @param path
  *  The path to be checked.
  *
- * @returns {boolean}
+ * @returns
  *  Whether the passed path refers to an existing file (returns `false` for
  *  existing directories).
  */
 export function isFile(path) {
     try {
         return lstatSync(path).isFile();
-    } catch {
+    }
+    catch {
         return false;
     }
 }
-
 /**
  * Returns whether a module name matches the specified glob patterns.
  *
- * @param {string} moduleName
+ * @param moduleName
  *  The module name to be checked.
  *
- * @param {import("picomatch").Glob} patterns
+ * @param patterns
  *  The glob patterns to be matched against the module name.
  *
- * @returns {boolean}
+ * @returns
  *  Whether the module name matches at least one glob pattern.
  */
 export const matchModuleName = pm.isMatch;
-
 /**
  * Extracts the source node and module name of an import/export statement node,
  * or a dynamic import expression node.
  *
- * @typedef {import("acorn").Node} Node
- *
- * @param {Node} node
+ * @param node
  *  The import/export statement node, or dynamic import expression node.
  *
- * @returns {{ sourceNode: Node | undefined; moduleName: string }}
+ * @returns
  *  The string literal node containing the module name, and the resulting
  *  extracted module name.
  */
 export function getModuleName(node) {
-
     // TSExternalModuleReference: module name in property "expression", otherwise "source"
-    const sourceNode = (node.type === "TSExternalModuleReference") ? node.expression : node.source;
-
+    const sourceNodeRaw = (node.type === NodeType.TSExternalModuleReference) ? node.expression : node.source;
     // module name is expected to be a string literal
-    const isStringLiteral = (sourceNode?.type === "Literal") && (typeof sourceNode.value === "string");
-
+    const isStringLiteral = (sourceNodeRaw?.type === NodeType.Literal) && (typeof sourceNodeRaw.value === "string");
+    const sourceNode = isStringLiteral ? sourceNodeRaw : undefined;
     // strip URL query strings from module name
-    const moduleName = isStringLiteral ? sourceNode.value.replace(/\?.*$/, "") : "";
-
+    const moduleName = sourceNode ? sourceNode.value.replace(/\?.*$/, "") : "";
     return { sourceNode, moduleName };
 }

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * as utils from "./utils/index.js";
+export * as eslint from "./eslint/index.js";
+export * as stylelint from "./stylelint/index.js";

package/{lib → dist}/index.js

@@ -1,4 +1,3 @@
-
 export * as utils from "./utils/index.js";
 export * as eslint from "./eslint/index.js";
 export * as stylelint from "./stylelint/index.js";

package/dist/stylelint/index.d.ts

@@ -0,0 +1,49 @@
+import type { Config } from "stylelint";
+/**
+ * Configuration options for StyleLint code style rules.
+ */
+export interface StylisticOptions {
+    /**
+     * Default indentation size (number of space characters). Default value is
+     * `2`.
+     */
+    indent?: number;
+    /**
+     * The type of the string delimiter character. Default value is "single".
+     */
+    quotes?: "single" | "double" | "off";
+}
+/**
+ * Configuration options for linting the entire project with StyleLint.
+ */
+export interface ConfigureOptions {
+    /**
+     * 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.
+     */
+    license?: string;
+    /**
+     * Configuration options for code style.
+     */
+    stylistic?: StylisticOptions;
+    /**
+     * Additional linter rules to be added to the global configuration.
+     */
+    rules?: Config["rules"];
+}
+/**
+ * Generates a StyleLint configuration object targeting the source files in the
+ * entire project.
+ *
+ * @param options
+ *  Plugin configuration options.
+ *
+ * @returns
+ *  The configuration object to be exported from `stylelint.config.js`.
+ */
+export declare function configure(options?: ConfigureOptions): Config;

package/{lib → dist}/stylelint/index.js

@@ -1,55 +1,44 @@
-
 // functions ==================================================================
-
 /**
- * Generates standard configuration objects targeting the source files in the
+ * Generates a StyleLint configuration object targeting the source files in the
  * entire project.
  *
- * @param {import("./types").ConfigureOptions} [options]
+ * @param options
  *  Plugin configuration options.
  *
- * @returns {import("stylelint").Config}
+ * @returns
  *  The configuration object to be exported from `stylelint.config.js`.
  */
 export function configure(options) {
-
     // resolve stylistic configuration options
     const stylistic = {
         indent: 2,
         quotes: "single",
         ...options?.stylistic,
     };
-
-    // group custom rules by language plugins
     const rules = { base: {}, scss: {}, less: {} };
     for (const [rule, value] of Object.entries(options?.rules ?? {})) {
-        (rules[rule.split("/")[0]] ?? rules.base)[rule] = value;
+        const key = rule.split("/")[0];
+        (rules[key] ?? rules.base)[rule] = value;
     }
-
     return {
-
         // ignore certain files and folders
         ignoreFiles: options?.ignores ?? [],
-
         // add the stylistic plugin
         plugins: [
             "stylelint-plugin-license-header",
             "@stylistic/stylelint-plugin",
         ],
-
         // add recommended configurations
         extends: [
             "@stylistic/stylelint-config",
         ],
-
         // check inline directives
         reportDescriptionlessDisables: null,
         reportInvalidScopeDisables: true,
         reportNeedlessDisables: true,
-
         // reconfigure linter rules
         rules: {
-
             // core rules
             "at-rule-empty-line-before": null,
             "color-function-notation": ["modern", { ignore: ["with-var-inside"] }],
@@ -65,24 +54,19 @@ export function configure(options) {
             "no-descending-specificity": null,
             "no-unknown-animations": true,
             "rule-empty-line-before": null,
-
             // license-header plugin
             ...(options?.license ? { "plugin/license-header": [true, { license: options.license }] } : null),
-
             // stylistic plugin
             "@stylistic/declaration-colon-newline-after": null,
             "@stylistic/indentation": [stylistic.indent, { ignore: ["inside-parens"] }],
             "@stylistic/max-line-length": null,
             "@stylistic/selector-list-comma-newline-after": null,
             "@stylistic/string-quotes": (stylistic.quotes === "off") ? null : [stylistic.quotes, { avoidEscape: true }],
-
             // custom rules
             ...rules.base,
         },
-
         // overrides for custom languages
         overrides: [
-
             // SCSS files
             {
                 files: ["**/*.scss"],
@@ -92,7 +76,6 @@ export function configure(options) {
                     ...rules.scss,
                 },
             },
-
             // LESS files
             {
                 files: ["**/*.less"],

package/dist/utils/index.d.ts

@@ -0,0 +1,12 @@
+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.
+ */
+export declare function resolver(url: string): FileResolveFn;

package/{lib → dist}/utils/index.js

@@ -1,16 +1,13 @@
-
 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 {string} url
+ * @param url
  *  The base URL of the calling script, usually `import.meta.url`.
  *
- * @returns {(file: string) => string}
+ * @returns
  *  A function that converts relative file paths to absolute file paths.
  */
 export function resolver(url) {

package/package.json

@@ -1,17 +1,21 @@
 {
     "name": "@open-xchange/linter-presets",
-    "version": "0.0.6",
+    "version": "0.1.0",
     "description": "Configuration presets for ESLint and StyleLint",
-    "repository": "https://gitlab.open-xchange.com/fspd/npm-packages/linter-presets",
+    "repository": {
+        "url": "https://gitlab.open-xchange.com/fspd/npm-packages/linter-presets"
+    },
     "license": "MIT",
     "engines": {
         "node": ">=18"
     },
     "packageManager": "yarn@4.3.1",
     "type": "module",
-    "exports": "./lib/index.js",
+    "exports": "./dist/index.js",
     "scripts": {
         "prepare": "husky",
+        "prepack": "yarn lint && yarn build",
+        "build": "npx --yes rimraf dist && tsc",
         "lint": "eslint ."
     },
     "lint-staged": {
@@ -56,7 +60,11 @@
         "typescript-eslint": "7.16.0"
     },
     "devDependencies": {
-        "@types/acorn": "6.0.0",
+        "@types/confusing-browser-globals": "1.0.3",
+        "@types/eslint__js": "8.42.3",
+        "@types/json-schema": "7.0.15",
+        "@types/picomatch": "3.0.0",
+        "@typescript-eslint/utils": "7.16.0",
         "eslint": "9.6.0",
         "husky": "9.0.11",
         "jest": "29.7.0",

package/lib/eslint/config/imports.js

@@ -1,68 +0,0 @@
-
-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,36 +0,0 @@
-
-import { NO_UNUSED_VARS_OPTIONS } from "../shared/env-utils.js";
-
-// functions ==================================================================
-
-/**
- * Defines additional standard rules targeting JavaScript but _not_ TypeScript
- * source files.
- *
- * @returns {import("../shared/types.js").FlatConfigArray}
- *  An array of configuration objects to be added to the flat configuration.
- */
-export default function js() {
-
-    return [{
-        files: ["**/*.{js,jsx,cjs,mjs}"],
-        rules: {
-            // possible problems
-            "no-duplicate-imports": "error",
-            "no-loss-of-precision": "off",
-            "no-unused-vars": ["error", NO_UNUSED_VARS_OPTIONS],
-            // suggestions
-            "default-param-last": "error",
-            "dot-notation": "error",
-            "no-array-constructor": "error",
-            "no-invalid-this": "error",
-            "no-loop-func": "error",
-            "no-redeclare": "error",
-            "no-shadow": ["error", { ignoreOnInitialization: true }],
-            "no-throw-literal": "error",
-            "no-useless-constructor": "error",
-            "prefer-promise-reject-errors": "error",
-            "require-await": "error",
-        },
-    }];
-}

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

@@ -1,21 +0,0 @@
-
-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 {
-
-    /**
-     * All globals, imports, properties, and syntax constructs to be banned for
-     * the files included by the environment.
-     */
-    restricted?: EnvRestrictedOptions;
-}
-
-// functions ==================================================================
-
-export default function browser(options: EnvBrowserOptions): FlatConfigArray;

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

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

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

@@ -1,14 +0,0 @@
-
-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/jest.d.ts

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

package/lib/eslint/env/jest.js

@@ -1,56 +0,0 @@
-
-import jestPlugin from "eslint-plugin-jest";
-
-// functions ==================================================================
-
-/**
- * Creates configuration objects with global symbols and linter rules for unit
- * tests using Jest.
- *
- * Wraps the following packages:
- * - `eslint-plugin-jest`
- *
- * @param {import("./jest").EnvJestOptions} 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 jest(options) {
-
-    // config properties
-    const { files, ignores = [], rules } = options;
-
-    return [{
-        files,
-        ignores,
-
-        // register rule implementations, globals
-        ...jestPlugin.configs["flat/recommended"],
-
-        // configure plugin rules
-        rules: {
-            // recommended rules
-            ...jestPlugin.configs["flat/recommended"].rules,
-            ...jestPlugin.configs["flat/style"].rules,
-            // extra rules
-            "jest/consistent-test-it": ["error", { fn: "it" }],
-            "jest/no-commented-out-tests": "error",
-            "jest/no-conditional-expect": "off",
-            "jest/no-confusing-set-timeout": "error",
-            "jest/no-duplicate-hooks": "error",
-            "jest/no-test-return-statement": "error",
-            "jest/prefer-comparison-matcher": "error",
-            "jest/prefer-equality-matcher": "error",
-            "jest/prefer-expect-resolves": "error",
-            "jest/prefer-hooks-on-top": "error",
-            "jest/prefer-lowercase-title": "error",
-            "jest/prefer-mock-promise-shorthand": "error",
-            "jest/prefer-spy-on": "error",
-            "jest/prefer-todo": "error",
-            "jest/require-top-level-describe": "error",
-            // custom rules
-            ...rules,
-        },
-    }];
-}

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

@@ -1,28 +0,0 @@
-
-import { FlatConfigArray, LanguageOptions } from "../shared/types";
-import { EnvBaseOptions, EnvRestrictedOptions } from "../shared/env-utils";
-
-// types ======================================================================
-
-/**
- * Configuration options for the environment preset "env.node".
- */
-export interface EnvNodeOptions extends EnvBaseOptions {
-
-    /**
-     * The module mode used by the linted files.
-     *
-     * 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 ==================================================================
-
-export default function node(options: EnvNodeOptions): FlatConfigArray;