@open-xchange/linter-presets 0.0.2 → 0.0.4

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

@@ -0,0 +1,205 @@
+/*
+ * @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.
+ *
+ */
+
+import { createRequire } from "node:module";
+import { posix, dirname, extname } from "node:path";
+
+import { packageUpSync } from "package-up";
+
+import { Schema, makeArray, toPosixPath, isFile, matchModuleName, getModuleName } from "../shared/rule-utils.js";
+
+// constants ==================================================================
+
+const FILE_EXTENSIONS = ["js", "ts", "d.ts"];
+
+// exports ====================================================================
+
+/** @type {import("eslint").Rule.RuleModule} */
+export default {
+
+    meta: {
+        type: "problem",
+        schema: [
+            // single options object
+            Schema.options({
+                alias: Schema.dictionary(Schema.string()), // alias paths may be empty
+                external: Schema.maybeArray(Schema.stringNE()),
+                packages: Schema.dictionary(Schema.options({
+                    src: Schema.maybeArray(Schema.stringNE()),
+                    dependsOn: Schema.maybeArray(Schema.stringNE()),
+                    optional: Schema.boolean(),
+                }, ["src"])),
+            }),
+        ],
+        messages: {
+            SOURCE_FILE_NOT_FOUND: "Source file for '{{moduleName}}' not found.",
+            UNEXPECTED_OPTIONAL_STATIC: "Unexpected static import of optional package.",
+            INVALID_PACKAGE_HIERARCHY: "Low-level package cannot import modules from higher-level package.",
+        },
+        fixable: "code",
+    },
+
+    create(context) {
+
+        // resolve and decompose rule settings
+        const {
+            alias = {},
+            external: externalModules = [],
+            packages = {},
+        } = context.options[0] || {};
+
+        // convert "alias" option to map
+        const aliasMap = new Map(Object.entries(alias));
+
+        // convert "packages" option (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);
+        }
+
+        // resolve file name
+        const packagePath = packageUpSync();
+        const rootDir = toPosixPath(dirname(packagePath));
+        const fileName = toPosixPath(context.filename);
+        if (!fileName.startsWith(rootDir + "/")) {
+            throw new Error("invalid root directory");
+        }
+
+        // path of current module (slice rootDir with "/" from start, and extension with "." from end)
+        const fileExt = extname(fileName);
+        const selfModulePath = fileName.slice(rootDir.length + 1, -fileExt.length);
+        if (!selfModulePath) {
+            throw new Error("invalid own module path");
+        }
+
+        // replace alias path with alias key
+        let selfModuleName = selfModulePath;
+        for (const [aliasKey, aliasPath] of aliasMap) {
+            if (selfModulePath.startsWith(aliasPath + "/")) {
+                selfModuleName = aliasKey + "/" + selfModulePath.slice(aliasPath.length + 1);
+                break;
+            }
+        }
+
+        // returns an existing alias key used by the passed module name
+        const resolveAlias = moduleName => {
+            const [key, ...rest] = moduleName.split("/");
+            const aliasPath = (key && rest[0]) ? aliasMap.get(key) : undefined;
+            const aliasKey = aliasPath ? key : "";
+            const modulePath = aliasPath ? posix.join(aliasPath, ...rest) : moduleName;
+            return { aliasKey, modulePath };
+        };
+
+        // returns whether a source file exists for the specified module
+        const fileExists = resolvedName => {
+            // check modules with explicit extension
+            const resolvedPath = posix.join(rootDir, resolvedName);
+            if (extname(resolvedName)) { return isFile(resolvedPath); }
+            // search for a file with a known extension
+            return FILE_EXTENSIONS.some(ext => isFile(resolvedPath + "." + ext));
+        };
+
+        // returns whether the passed module name is an installed NPM package
+        const requireModule = createRequire(packagePath);
+        const packageExists = moduleName => {
+            try {
+                requireModule.resolve(moduleName);
+                return true;
+            } catch {
+                return false;
+            }
+        };
+
+        return {
+            "ImportDeclaration, TSExternalModuleReference, ImportExpression, ExportAllDeclaration, ExportNamedDeclaration"(node) {
+
+                // import/export statement must contain string literal
+                const { sourceNode, moduleName } = getModuleName(node);
+                if (!sourceNode || !moduleName) { return; }
+
+                // skip glob patterns in TypeScript type imports
+                if ((node.type === "ImportDeclaration") && (node.importKind === "type") && moduleName.includes("*")) {
+                    return;
+                }
+
+                // extract alias key, replace with alias path
+                const { aliasKey, modulePath } = resolveAlias(moduleName);
+
+                // whether the import is a known external module
+                const isExternal = !aliasKey && matchModuleName(moduleName, externalModules);
+
+                // whether the import is an installed NPM package
+                const isPackage = !isExternal && !aliasKey && packageExists(moduleName);
+
+                // check existence of source file
+                if (!isExternal && !isPackage && !fileExists(modulePath)) {
+                    context.report({ messageId: "SOURCE_FILE_NOT_FOUND", node: sourceNode, data: { moduleName } });
+                    return;
+                }
+
+                // check dependencies if the imported module is covered in the configuration
+                if (!matchModuleName(moduleName, packagesGlobs)) { return; }
+
+                // check package dependencies
+                // whether an invalid static import has been found
+                let invalidStatic = false;
+
+                // recursively checks the imported module for dependency violations
+                const checkDependencies = (settings, root) => {
+
+                    // only allow static imports from specified package, if it is not optional
+                    if (matchModuleName(moduleName, settings.src)) {
+                        if (!root && (node.type !== "ImportExpression") && settings.optional) { invalidStatic = true; }
+                        return true;
+                    }
+
+                    // do not traverse into dependencies of optional modules
+                    if ((settings.dependsOn.length === 0) || (!root && settings.optional)) {
+                        return false;
+                    }
+
+                    // allow imports from any of the dependent packages
+                    return settings.dependsOn.some(key => checkDependencies(packagesMap.get(key), false));
+                };
+
+                // check dependencies of all configured packages (not for anonymous modules)
+                let invalidDeps = false;
+                for (const settings of packagesMap.values()) {
+                    if (matchModuleName(selfModuleName, settings.src) && !checkDependencies(settings, true)) {
+                        invalidDeps = true;
+                        break;
+                    }
+                }
+
+                // report package hierarchy errors
+                if (invalidStatic) {
+                    context.report({ messageId: "UNEXPECTED_OPTIONAL_STATIC", node: sourceNode });
+                } else if (invalidDeps) {
+                    context.report({ messageId: "INVALID_PACKAGE_HIERARCHY", node: sourceNode });
+                }
+            },
+        };
+    },
+};

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

@@ -0,0 +1,97 @@
+
+import { Linter } from "eslint";
+
+import { FlatConfigArray } from "./types";
+
+// types ======================================================================
+
+/**
+ * Shared options for an environment preset with included and excluded files.
+ */
+export interface EnvFilesOptions {
+
+    /**
+     * Glob patterns for source files to be included into the environment.
+     */
+    files: readonly string[];
+
+    /**
+     * Glob patterns for source files matching `files` to be ignored.
+     */
+    ignores?: readonly string[];
+}
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Shared options for an environment preset: include and exclude files, and add
+ * more linter rules.
+ */
+export interface EnvBaseOptions extends EnvFilesOptions {
+
+    /**
+     * Additional linter rules to be added to the configuration.
+     */
+    rules?: Linter.RulesRecord;
+}
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Configuration for a single banned global or import.
+ */
+export interface EnvRestrictedName {
+    name: string;
+    message: string;
+}
+
+/**
+ * Configuration for a single banned object property.
+ */
+export interface EnvRestrictedProperty {
+    object: string;
+    property: string;
+    message: string;
+}
+
+/**
+ * Configuration for a single banned syntax construct.
+ */
+export interface EnvRestrictedSyntax {
+    selector: string;
+    message: string;
+}
+
+/**
+ * Collection of banned globals, imports, properties, and syntax constructs.
+ */
+export interface EnvRestrictedItems {
+    /** The global symbols to be banned. */
+    globals?: readonly EnvRestrictedName[];
+    /** The module imports to be banned. */
+    imports?: readonly EnvRestrictedName[];
+    /** The global object properties to be banned. */
+    properties?: readonly EnvRestrictedProperty[];
+    /** The syntax constructs to be banned. */
+    syntax?: readonly EnvRestrictedSyntax[];
+}
+
+/**
+ * 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;
+}
+
+/**
+ * Configuration options for restricted imports and globals.
+ */
+export interface EnvRestrictedOptions extends EnvRestrictedItems {
+    overrides?: readonly EnvRestrictedOverride[];
+}
+
+export interface EnvRestrictedRulesResult {
+    rules: Linter.RulesRecord;
+    overrides: FlatConfigArray;
+}

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

@@ -0,0 +1,105 @@
+
+// constants ==================================================================
+
+/**
+ * Global symbols to be banned in all source code files.
+ */
+const RESTRICTED_GLOBALS = [
+    { name: "isFinite", message: "Use 'Number.isFinite' instead." },
+    { name: "isNaN", message: "Use 'Number.isNaN' instead." },
+];
+
+/**
+ * Syntax constructs to be banned in all source code files.
+ */
+const RESTRICTED_SYNTAX = [
+    { selector: ":matches(PropertyDefinition, MethodDefinition[kind!='constructor'])[accessibility='public']", message: "Remove 'public' keyword." },
+    { selector: ":matches(PropertyDefinition, MethodDefinition[kind!='constructor'])[accessibility='private'][decorators.length=0]", message: "Use #private syntax instead." },
+    { selector: "MethodDefinition[kind='constructor'] TSParameterProperty[accessibility]", message: "Use explicit class properties." },
+];
+
+/**
+ * Shared options for the core rule `no-unused-vars`, and the plugin rule
+ * `@typescript-eslint/no-unused-vars`.
+ */
+export const NO_UNUSED_VARS_OPTIONS = {
+    varsIgnorePattern: "^_",
+    argsIgnorePattern: "^_",
+    destructuredArrayIgnorePattern: "^_",
+    caughtErrors: "all",
+    ignoreRestSiblings: true,
+};
+
+// functions ==================================================================
+
+/**
+ * Concatenates the elements of multiple arrays. Skips all falsy parameters.
+ *
+ * @template T
+ *
+ * @param {Array<T[] | undefined | null | false>} arrays
+ *  The arrays to be concatenated.
+ *
+ * @returns {T[]}
+ *  The concatenated arrays.
+ */
+function flatten(...arrays) {
+    return arrays.flatMap(array => array || []);
+}
+
+/**
+ * Creates a rules record for all restricted items.
+ *
+ * @param {(key: string) => object[]} generator
+ *  The generator callback function that returns the restricted items to be
+ *  inserted into the linter rules.
+ *
+ * @returns {import("eslint").Linter.RulesRecord}
+ *  The rules record containing entries for all existing restricted items.
+ */
+function createRulesRecord(generator) {
+    const rules = {};
+    for (const key of ["globals", "imports", "properties", "syntax"]) {
+        const items = generator(key);
+        if (items?.length) { rules[`no-restricted-${key}`] = ["error", ...items]; }
+    }
+    return rules;
+}
+
+/**
+ * Generates various "no-restricted-?" rules from the passed configuration.
+ *
+ * @param {import("./env-utils").EnvRestrictedItems} fixed
+ *  The fixed restricted items provided by the environment preset.
+ *
+ * @param {import("./env-utils").EnvRestrictedOptions} [options]
+ *  The custom configuration passed to an environment preset.
+ *
+ * @returns {import("./env-utils").EnvRestrictedRulesResult}
+ *  The generated linter rules to forbid the restricted items.
+ */
+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),
+    };
+
+    // base rules for all files in the environment
+    const rules = createRulesRecord(key => items[key]);
+
+    // generate the override entries (join with base items if specified)
+    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])),
+        });
+    }
+
+    return { rules, overrides };
+}

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

@@ -0,0 +1,162 @@
+/*
+ * @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.
+ *
+ */
+
+import { posix, sep } from "node:path";
+import { lstatSync } from "node:fs";
+
+import pm from "picomatch";
+
+// 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 };
+    },
+
+    stringNE(options) {
+        return Schema.string({ minLength: 1, ...options });
+    },
+
+    array(items) {
+        return { type: "array", items, uniqueItems: true };
+    },
+
+    maybeArray(items) {
+        return { oneOf: [items, Schema.array(items)] };
+    },
+
+    dictionary(items) {
+        return { type: "object", additionalProperties: items };
+    },
+
+    options(properties, required) {
+        return { type: "object", properties, required, additionalProperties: false };
+    },
+};
+
+// functions ==================================================================
+
+/**
+ * Returns whether the passed value is nullish (either `undefined` or `null`).
+ *
+ * @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
+ *  Any value to be converted to an array.
+ *
+ * @returns {unknown[]}
+ *  An array containing the value, unless the value is already an array.
+ */
+export function makeArray(value) {
+    return Array.isArray(value) ? value : isNullish(value) ? [] : [value];
+}
+
+/**
+ * Converts a Windows file path to a Posix file path.
+ *
+ * @param {string} path
+ *  The file path to be normalized to Posix format.
+ *
+ * @returns {string}
+ *  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
+ *  The path to be checked.
+ *
+ * @returns {boolean}
+ *  Whether the passed path refers to an existing file (returns `false` for
+ *  existing directories).
+ */
+export function isFile(path) {
+    try {
+        return lstatSync(path).isFile();
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Returns whether a module name matches the specified glob patterns.
+ *
+ * @param {string} moduleName
+ *  The module name to be checked.
+ *
+ * @param {import("picomatch").Glob} patterns
+ *  The glob patterns to be matched against the module name.
+ *
+ * @returns {boolean}
+ *  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
+ *  The import/export statement node, or dynamic import expression node.
+ *
+ * @returns {{ sourceNode: Node | undefined; moduleName: string }}
+ *  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;
+
+    // module name is expected to be a string literal
+    const isStringLiteral = (sourceNode?.type === "Literal") && (typeof sourceNode.value === "string");
+
+    // strip URL query strings from module name
+    const moduleName = isStringLiteral ? sourceNode.value.replace(/\?.*$/, "") : "";
+
+    return { sourceNode, moduleName };
+}

package/lib/eslint/shared/types.d.ts

@@ -76,7 +76,7 @@ export interface StylisticOptions {
 /**
  * Configuration options for linting the entire project with ESLint.
  */
-export interface ESLintConfigureOptions {
+export interface ConfigureOptions {
 
     /**
      * Glob patterns with all files and folders to be ignored by ESLint.
@@ -105,27 +105,3 @@ export interface ESLintConfigureOptions {
      */
     rules?: Linter.RulesRecord;
 }
-
-// ----------------------------------------------------------------------------
-
-/**
- * Shared options for an environment preset: include and exclude files, and add
- * more linter rules.
- */
-export interface EnvBaseOptions {
-
-    /**
-     * Glob patterns for source files to be included into the environment.
-     */
-    files: readonly string[];
-
-    /**
-     * Glob patterns for source files matching `files` to be ignored.
-     */
-    ignores?: readonly string[];
-
-    /**
-     * Additional linter rules to be added to the configuration.
-     */
-    rules?: Linter.RulesRecord;
-}

package/lib/index.d.ts

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

package/{doc/stylelint.md → lib/stylelint/README.md}

@@ -8,9 +8,16 @@ The module `stylelint` provides a `configure` function for project-wide StyleLin
 
 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.
 
+| Target | StyleLint Plugin |
+| - | - |
+| Stylesheet files (`.css`, `.less`, `.scss`) | StyleLint core rules |
+| Less files only | [stylelint-config-standard-less](https://github.com/stylelint-less/stylelint-config-standard-less) |
+| Sass files only | [stylelint-config-standard-scss](https://github.com/stylelint-scss/stylelint-config-standard-scss) |
+| Source code formatting | [@stylistic/stylelint-plugin](https://github.com/stylelint-stylistic/stylelint-stylistic) |
+
 #### `configure` Signature
 
-`function configure(options?: StyleLintConfigureOptions): Linter.FlatConfig[]`
+`function configure(options?: ConfigureOptions): Linter.FlatConfig[]`
 
 #### `configure` Options
 
@@ -19,9 +26,9 @@ Generates standard configuration targeting the source files in the entire projec
 | `ignores` | `string[]` | `[]` | Glob patterns with all files and folders to be ignored by StyleLint. |
 | `license` | `string` | `""` | Full path to the template file containing the license header to be used in all source files. |
 | `stylistic` | `StylisticOptions` | | Configuration options for code style. |
-| `stylistic.indent` | `number` | `2` | Default indentation size (number of space characters). Will be applied to JavaScript, TypeScript, JSON, and YAML files, as well as JSX markup. |
+| `stylistic.indent` | `number` | `2` | Default indentation size (number of space characters). |
 | `stylistic.quotes` | `"single"\|"double"\|"off"` | `"single"` | The type of the string delimiter character. |
-| `rules` | `Linter.RulesRecord` | `{}` | Additional linter rules to be added to the global configuration. |
+| `rules` | `StyleLint.Config["rules"]` | `{}` | Additional linter rules to be added to the global configuration. |
 
 #### `configure` Example
 

package/lib/stylelint/index.d.ts

@@ -1,7 +1,7 @@
 
 import { Config } from "stylelint";
 
-import { StyleLintConfigureOptions } from "./types";
+import { ConfigureOptions } from "./types";
 
 // functions ==================================================================
 
@@ -15,4 +15,4 @@ import { StyleLintConfigureOptions } from "./types";
  * @returns
  *  An array of configuration objects to be added to the flat configuration.
  */
-export function configure(config?: StyleLintConfigureOptions): Config;
+export function configure(config?: ConfigureOptions): Config;