@open-xchange/linter-presets 0.1.6 → 0.1.7

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [0.1.7] - 2024-07-23
+
+- changed: [ESLint] reverted option `modules` for `env.project` (introduced in 0.1.6)
+- changed: [ESLint] `env.project`: renamed option `packages` to `hierarchy`
+- chore: [ESLint] split rule `env-project/no-invalid-modules` (added `env-project/no-invalid-hierarchy`)
+
 ## [0.1.6] - 2024-07-23
 
 - changed: [ESLint] moved rule options for `env.project` into own `modules` option
@@ -31,7 +37,7 @@
 
 ## [0.0.6] - 2024-07-10
 
-- fixed: [ESLint] type error in `env-project/no-invalid-modules`
+- fixed: [ESLint] type error in rule `env-project/no-invalid-modules`
 
 ## [0.0.5] - 2024-07-10
 

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

@@ -1,14 +1,24 @@
 import type { TSESLint } from "@typescript-eslint/utils";
 import type { EnvBaseOptions } from "../shared/env-utils.js";
+import type { SharedRuleSettings } from "../shared/rule-utils.js";
 import { type RuleNoInvalidModulesOptions } from "../rules/no-invalid-modules.js";
+import { type RuleNoInvalidHierarchyOptions } from "../rules/no-invalid-hierarchy.js";
 /**
  * Configuration options for the environment preset "env.project".
  */
 export interface EnvProjectOptions extends EnvBaseOptions {
+    /**
+     * Maps all alias prefixes to actual paths in the project.
+     */
+    alias?: SharedRuleSettings["alias"];
     /**
      * Options to be passed to the rule "env-project/no-invalid-modules".
      */
-    modules?: RuleNoInvalidModulesOptions;
+    external?: RuleNoInvalidModulesOptions["external"];
+    /**
+     * Options to be passed to the rule "env-project/no-invalid-hierarchy".
+     */
+    hierarchy?: RuleNoInvalidHierarchyOptions;
 }
 /**
  * Adds custom linter rules for checking project setup and module hierarchy.

package/dist/eslint/env/project.js

@@ -1,6 +1,7 @@
 import { concatConfigs, createConfig, customRules } from "../shared/env-utils.js";
 import noAmdModuleDirective from "../rules/no-amd-module-directive.js";
 import noInvalidModules from "../rules/no-invalid-modules.js";
+import noInvalidHierarchy from "../rules/no-invalid-hierarchy.js";
 // exports ====================================================================
 /**
  * Adds custom linter rules for checking project setup and module hierarchy.
@@ -20,13 +21,20 @@ export default function project(envOptions) {
                 rules: {
                     "no-amd-module-directive": noAmdModuleDirective,
                     "no-invalid-modules": noInvalidModules,
+                    "no-invalid-hierarchy": noInvalidHierarchy,
                 },
             },
         },
+        settings: {
+            "env-project": {
+                alias: envOptions.alias,
+            },
+        },
     }), 
     // custom rules
     customRules(envOptions, {
         "env-project/no-amd-module-directive": "error",
-        "env-project/no-invalid-modules": ["error", envOptions.modules ?? {}],
+        "env-project/no-invalid-modules": ["error", { external: envOptions.external }],
+        "env-project/no-invalid-hierarchy": envOptions.hierarchy ? ["error", envOptions.hierarchy] : "off",
     }));
 }

package/dist/eslint/rules/no-invalid-hierarchy.d.ts

@@ -0,0 +1,25 @@
+import { ESLintUtils } from "@typescript-eslint/utils";
+export interface RuleNoInvalidHierarchyPackage {
+    /**
+     * Glob patterns selecting all source files that are part of the package.
+     */
+    files: string[];
+    /**
+     * Specifies the names of all packages (keys of the `packages` dictionary)
+     * this package depends on.
+     */
+    extends?: string | string[];
+    /**
+     * 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. Default value is `false`.
+     */
+    optional?: boolean;
+}
+export type RuleNoInvalidHierarchyOptions = Record<string, RuleNoInvalidHierarchyPackage>;
+type RuleOptions = [RuleNoInvalidHierarchyOptions];
+type RuleMessageIds = "UNEXPECTED_OPTIONAL_STATIC" | "INVALID_PACKAGE_HIERARCHY";
+declare const _default: ESLintUtils.RuleModule<RuleMessageIds, RuleOptions, ESLintUtils.RuleListener>;
+export default _default;

package/dist/eslint/rules/no-invalid-hierarchy.js

@@ -0,0 +1,85 @@
+import { AST_NODE_TYPES as NodeType, ESLintUtils } from "@typescript-eslint/utils";
+import { Schema, makeArray, ProjectContext } from "../shared/rule-utils.js";
+// exports ====================================================================
+export default ESLintUtils.RuleCreator.withoutDocs({
+    meta: {
+        type: "problem",
+        schema: [
+            // single options object
+            Schema.dictionary(Schema.options({
+                files: Schema.maybeArray(Schema.stringNE()),
+                extends: Schema.maybeArray(Schema.stringNE()),
+                optional: Schema.boolean(),
+            }, ["files"])),
+        ],
+        messages: {
+            UNEXPECTED_OPTIONAL_STATIC: "Unexpected static import of optional package.",
+            INVALID_PACKAGE_HIERARCHY: "Low-level package cannot import modules from higher-level package.",
+        },
+        fixable: "code",
+    },
+    defaultOptions: [{}],
+    create(context, [options]) {
+        // create the project context with aliases, root path, own module name, etc.
+        const projectContext = new ProjectContext(context);
+        const hierarchyMap = new Map();
+        for (const [key, settings] of Object.entries(options)) {
+            hierarchyMap.set(key, {
+                ...settings,
+                extends: makeArray(settings.extends),
+            });
+        }
+        // collect all globs for package members
+        const packagesGlobs = Array.from(hierarchyMap.values(), settings => settings.files).flat();
+        return {
+            "ImportDeclaration, TSExternalModuleReference, ImportExpression, ExportAllDeclaration, ExportNamedDeclaration"(node) {
+                // import/export statement must contain string literal
+                const importWrapper = projectContext.resolveImportNode(node);
+                if (!importWrapper) {
+                    return;
+                }
+                // check dependencies if the imported module is covered in the configuration
+                if (!importWrapper.matchModuleName(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 (importWrapper.matchModuleName(settings.files)) {
+                        if (!root && (node.type !== NodeType.ImportExpression) && settings.optional) {
+                            invalidStatic = true;
+                        }
+                        return true;
+                    }
+                    // do not traverse into dependencies of optional modules
+                    if (!settings.extends.length || (!root && settings.optional)) {
+                        return false;
+                    }
+                    // allow imports from any of the dependent packages
+                    return settings.extends.some(key => {
+                        const package2 = hierarchyMap.get(key);
+                        return !!package2 && checkDependencies(package2, false);
+                    });
+                };
+                // check dependencies of all configured packages (not for anonymous modules)
+                let invalidDeps = false;
+                for (const settings of hierarchyMap.values()) {
+                    if (projectContext.matchModuleName(settings.files) && !checkDependencies(settings, true)) {
+                        invalidDeps = true;
+                        break;
+                    }
+                }
+                // report package hierarchy errors
+                if (invalidStatic) {
+                    context.report({ messageId: "UNEXPECTED_OPTIONAL_STATIC", node: importWrapper.sourceNode });
+                }
+                else if (invalidDeps) {
+                    context.report({ messageId: "INVALID_PACKAGE_HIERARCHY", node: importWrapper.sourceNode });
+                }
+            },
+        };
+    },
+});

package/dist/eslint/rules/no-invalid-modules.d.ts

@@ -1,38 +1,10 @@
 import { ESLintUtils } from "@typescript-eslint/utils";
-export interface RuleNoInvalidModulesPackage {
-    /**
-     * Glob patterns selecting all source files that are part of the package.
-     */
-    src: string | string[];
-    /**
-     * Specifies the names of all packages (keys of the `packages` dictionary)
-     * this package depends on.
-     */
-    extends?: string | string[];
-    /**
-     * 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. Default value is `false`.
-     */
-    optional?: boolean;
-}
 export interface RuleNoInvalidModulesOptions {
-    /**
-     * Maps all alias prefixes to actual paths in the project.
-     */
-    alias?: Record<string, string>;
     /**
      * Specifies glob patterns for external modules.
      */
-    external?: string | string[];
-    /**
-     * Allows to separate the source files into virtual packages.
-     */
-    packages?: Record<string, RuleNoInvalidModulesPackage>;
+    external?: string[];
 }
 type RuleOptions = [Required<RuleNoInvalidModulesOptions>];
-type RuleMessageIds = "SOURCE_FILE_NOT_FOUND" | "UNEXPECTED_OPTIONAL_STATIC" | "INVALID_PACKAGE_HIERARCHY";
-declare const _default: ESLintUtils.RuleModule<RuleMessageIds, RuleOptions, ESLintUtils.RuleListener>;
+declare const _default: ESLintUtils.RuleModule<"SOURCE_FILE_NOT_FOUND", RuleOptions, ESLintUtils.RuleListener>;
 export default _default;

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

@@ -1,10 +1,5 @@
-import { createRequire } from "node:module";
-import { posix, dirname, extname } from "node:path";
-import { findUpSync } from "find-up";
 import { AST_NODE_TYPES as NodeType, ESLintUtils } from "@typescript-eslint/utils";
-import { Schema, makeArray, toPosixPath, isFile, matchModuleName, getModuleName } from "../shared/rule-utils.js";
-// constants ==================================================================
-const FILE_EXTENSIONS = ["js", "ts", "d.ts"];
+import { Schema, ProjectContext } from "../shared/rule-utils.js";
 // exports ====================================================================
 export default ESLintUtils.RuleCreator.withoutDocs({
     meta: {
@@ -12,152 +7,48 @@ export default ESLintUtils.RuleCreator.withoutDocs({
         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()),
-                    extends: Schema.maybeArray(Schema.stringNE()),
-                    optional: Schema.boolean(),
-                }, ["src"])),
+                external: Schema.array(Schema.stringNE()),
             }),
         ],
         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",
     },
     defaultOptions: [{
-            alias: {},
             external: [],
-            packages: {},
         }],
     create(context, [options]) {
-        // convert "alias" option to map
-        const aliasMap = new Map(Object.entries(options.alias));
-        const packagesMap = new Map();
-        for (const [key, settings] of Object.entries(options.packages)) {
-            packagesMap.set(key, {
-                ...settings,
-                src: makeArray(settings.src),
-                extends: makeArray(settings.extends),
-            });
-        }
-        // collect all globs for package members
-        const packagesGlobs = Array.from(packagesMap.values(), settings => settings.src).flat();
-        // resolve file name
-        const configPath = findUpSync("eslint.config.js");
-        const rootDir = configPath && toPosixPath(dirname(configPath));
-        const fileName = toPosixPath(context.filename);
-        if (!rootDir || !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(configPath);
-        const packageExists = (moduleName) => {
-            try {
-                requireModule.resolve(moduleName);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        };
+        // create the project context with aliases, root path, own module name, etc.
+        const projectContext = new ProjectContext(context);
         return {
             "ImportDeclaration, TSExternalModuleReference, ImportExpression, ExportAllDeclaration, ExportNamedDeclaration"(node) {
                 // import/export statement must contain string literal
-                const { sourceNode, moduleName } = getModuleName(node);
-                if (!sourceNode || !moduleName) {
+                const importWrapper = projectContext.resolveImportNode(node);
+                if (!importWrapper) {
                     return;
                 }
                 // skip glob patterns in TypeScript type imports
-                if ((node.type === NodeType.ImportDeclaration) && (node.importKind === "type") && moduleName.includes("*")) {
+                if ((node.type === NodeType.ImportDeclaration) && (node.importKind === "type") && importWrapper.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 = matchModuleName(moduleName, options.external);
-                // 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 } });
+                // accept known external module
+                if (importWrapper.matchModuleName(options.external)) {
                     return;
                 }
-                // check dependencies if the imported module is covered in the configuration
-                if (!matchModuleName(moduleName, packagesGlobs)) {
+                // extract alias key, replace with alias path
+                const [aliasKey, modulePath] = projectContext.resolveAlias(importWrapper.moduleName);
+                // accept installed NPM package
+                if (!aliasKey && projectContext.packageExists(modulePath)) {
                     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 !== NodeType.ImportExpression) && settings.optional) {
-                            invalidStatic = true;
-                        }
-                        return true;
-                    }
-                    // do not traverse into dependencies of optional modules
-                    if (!settings.extends.length || (!root && settings.optional)) {
-                        return false;
-                    }
-                    // allow imports from any of the dependent packages
-                    return settings.extends.some(key => {
-                        const package2 = packagesMap.get(key);
-                        return !!package2 && checkDependencies(package2, false);
+                // check existence of source file
+                if (!projectContext.fileExists(modulePath)) {
+                    context.report({
+                        messageId: "SOURCE_FILE_NOT_FOUND",
+                        node: importWrapper.sourceNode,
+                        data: { moduleName: importWrapper.moduleName },
                     });
-                };
-                // 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/dist/eslint/shared/rule-utils.d.ts

@@ -1,10 +1,15 @@
-import pm from "picomatch";
-import type { JSONSchema, TSESTree } from "@typescript-eslint/utils";
-export type ImportExportNode = TSESTree.ImportDeclaration | TSESTree.ImportExpression | TSESTree.ExportAllDeclaration | TSESTree.ExportNamedDeclaration | TSESTree.TSExternalModuleReference;
-export interface ModuleNameResult {
-    sourceNode: TSESTree.StringLiteral | undefined;
-    moduleName: string;
+import { type Glob } from "picomatch";
+import type { JSONSchema, TSESTree, TSESLint } from "@typescript-eslint/utils";
+/**
+ * Shared settings used by multiple rules.
+ */
+export interface SharedRuleSettings {
+    /**
+     * Maps all alias prefixes to actual paths in the project.
+     */
+    alias?: Record<string, string>;
 }
+export type ImportExportNode = TSESTree.ImportDeclaration | TSESTree.ImportExpression | TSESTree.ExportAllDeclaration | TSESTree.ExportNamedDeclaration | TSESTree.TSExternalModuleReference;
 /**
  * Helper functions to build a JSON schema for custom ESLint rules.
  */
@@ -49,28 +54,88 @@ export declare function toPosixPath(path: string): string;
  *  existing directories).
  */
 export declare function isFile(path: string): boolean;
+export declare class ImportNodeWrapper {
+    /** The string literal node containing the name of the imported module. */
+    readonly sourceNode: TSESTree.StringLiteral;
+    /** The original name of the imported module (with alias key). */
+    readonly moduleName: string;
+    constructor(node: TSESTree.StringLiteral);
+    /**
+     * Returns whether the name of the imported module matches the specified
+     * glob patterns.
+     *
+     * @param patterns
+     *  The glob patterns to be matched against the module name.
+     *
+     * @returns
+     *  Whether the name of the wrapped module matches at least one glob
+     *  pattern.
+     */
+    matchModuleName(patterns: Glob): boolean;
+}
 /**
- * Returns whether a module name matches the specified glob patterns.
- *
- * @param moduleName
- *  The module name to be checked.
- *
- * @param patterns
- *  The glob patterns to be matched against the module name.
- *
- * @returns
- *  Whether the module name matches at least one glob pattern.
- */
-export declare const matchModuleName: typeof pm.isMatch;
-/**
- * Extracts the source node and module name of an import/export statement node,
- * or a dynamic import expression node.
+ * A custom context helper for the linter rules of the preset environment
+ * "env.project".
  *
- * @param node
- *  The import/export statement node, or dynamic import expression node.
- *
- * @returns
- *  The string literal node containing the module name, and the resulting
- *  extracted module name.
+ * @param context
+ *  The rule context of the module currently linted.
  */
-export declare function getModuleName(node: ImportExportNode): ModuleNameResult;
+export declare class ProjectContext {
+    #private;
+    constructor(context: Readonly<TSESLint.RuleContext<any, any>>);
+    /**
+     * Extracts the source node and module name of an import/export statement
+     * node, or a dynamic import expression node.
+     *
+     * @param node
+     *  The import/export statement node, or dynamic import expression node.
+     *
+     * @returns
+     *  The string literal node containing the module name, and the resulting
+     *  extracted module name.
+     */
+    resolveImportNode(node: ImportExportNode): ImportNodeWrapper | undefined;
+    /**
+     * Extracts an existing alias key, and resolves the module path of a module
+     * name.
+     *
+     * @param moduleName
+     *  The module name to extract an alias key from.
+     *
+     * @returns
+     *  A pair containing the alias key (empty string if no alias found), and
+     *  the resolved module path (passed module name if no alias found).
+     */
+    resolveAlias(moduleName: string): [string, string];
+    /**
+     * Returns whether the name of the module currently linted matches the
+     * specified glob patterns.
+     *
+     * @param patterns
+     *  The glob patterns to be matched against the current module name.
+     *
+     * @returns
+     *  Whether the current module name matches at least one glob pattern.
+     */
+    matchModuleName(patterns: Glob): boolean;
+    /**
+     * Returns whether a source file exists for the specified module.
+     *
+     * @param modulePath
+     *  The resolved module path (alias key replaced with path).
+     *
+     * @returns
+     *  Whether a source file exists for the specified module.
+     */
+    fileExists(modulePath: string): boolean;
+    /**
+     * Returns whether the passed module name is an installed NPM package.
+     *
+     * @param moduleName
+     *  The module name to be checked.
+     *
+     * @returns
+     *  Whether the passed module name is an installed NPM package.
+     */
+    packageExists(moduleName: string): boolean;
+}

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

@@ -1,7 +1,11 @@
-import { posix, sep } from "node:path";
+import { posix, sep, dirname, extname } from "node:path";
 import { lstatSync } from "node:fs";
+import { createRequire } from "node:module";
 import pm from "picomatch";
+import { findUpSync } from "find-up";
 import { AST_NODE_TYPES as NodeType } from "@typescript-eslint/utils";
+// constants ==================================================================
+const FILE_EXTENSIONS = ["js", "ts", "d.ts"];
 // Schema =====================================================================
 /**
  * Helper functions to build a JSON schema for custom ESLint rules.
@@ -73,37 +77,167 @@ export function isFile(path) {
         return false;
     }
 }
+// class ImportNodeWrapper ====================================================
+export class ImportNodeWrapper {
+    /** The string literal node containing the name of the imported module. */
+    sourceNode;
+    /** The original name of the imported module (with alias key). */
+    moduleName;
+    // constructor ------------------------------------------------------------
+    constructor(node) {
+        this.sourceNode = node;
+        // strip URL query strings from module name
+        this.moduleName = node.value.replace(/\?.*$/, "");
+    }
+    // public methods ---------------------------------------------------------
+    /**
+     * Returns whether the name of the imported module matches the specified
+     * glob patterns.
+     *
+     * @param patterns
+     *  The glob patterns to be matched against the module name.
+     *
+     * @returns
+     *  Whether the name of the wrapped module matches at least one glob
+     *  pattern.
+     */
+    matchModuleName(patterns) {
+        return pm.isMatch(this.moduleName, patterns);
+    }
+}
+// class ProjectContext =======================================================
 /**
- * Returns whether a module name matches the specified glob patterns.
- *
- * @param moduleName
- *  The module name to be checked.
- *
- * @param patterns
- *  The glob patterns to be matched against the module name.
+ * A custom context helper for the linter rules of the preset environment
+ * "env.project".
  *
- * @returns
- *  Whether the module name matches at least one glob pattern.
+ * @param context
+ *  The rule context of the module currently linted.
  */
-export const matchModuleName = pm.isMatch;
-/**
- * Extracts the source node and module name of an import/export statement node,
- * or a dynamic import expression node.
- *
- * @param node
- *  The import/export statement node, or dynamic import expression node.
- *
- * @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 sourceNodeRaw = (node.type === NodeType.TSExternalModuleReference) ? node.expression : node.source;
-    // module name is expected to be a string literal
-    const isStringLiteral = (sourceNodeRaw?.type === NodeType.Literal) && (typeof sourceNodeRaw.value === "string");
-    const sourceNode = isStringLiteral ? sourceNodeRaw : undefined;
-    // strip URL query strings from module name
-    const moduleName = sourceNode ? sourceNode.value.replace(/\?.*$/, "") : "";
-    return { sourceNode, moduleName };
+export class ProjectContext {
+    /** Maps alias keys to alias paths. */
+    #aliasMap;
+    /** Root directory containing the linter configuration file. */
+    #rootDir;
+    /** Absolute path to the linter configuration file. */
+    #configPath;
+    /** The name of the linted module (with alias prefix if available). */
+    #moduleName;
+    /** Resolver for NPM packages. */
+    #requireModule;
+    // constructor ------------------------------------------------------------
+    constructor(context) {
+        // convert "alias" option to map
+        const sharedSettings = context.settings["env-project"];
+        this.#aliasMap = new Map(Object.entries(sharedSettings?.alias ?? {}));
+        // resolve root directory
+        const configPath = findUpSync("eslint.config.js");
+        const rootDir = configPath && toPosixPath(dirname(configPath));
+        const fileName = toPosixPath(context.filename);
+        if (!rootDir || !fileName.startsWith(rootDir + "/")) {
+            throw new Error("invalid root directory");
+        }
+        this.#rootDir = rootDir;
+        this.#configPath = configPath;
+        // 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
+        this.#moduleName = selfModulePath;
+        for (const [aliasKey, aliasPath] of this.#aliasMap) {
+            if (selfModulePath.startsWith(aliasPath + "/")) {
+                this.#moduleName = aliasKey + "/" + selfModulePath.slice(aliasPath.length + 1);
+                break;
+            }
+        }
+    }
+    // public methods ---------------------------------------------------------
+    /**
+     * Extracts the source node and module name of an import/export statement
+     * node, or a dynamic import expression node.
+     *
+     * @param node
+     *  The import/export statement node, or dynamic import expression node.
+     *
+     * @returns
+     *  The string literal node containing the module name, and the resulting
+     *  extracted module name.
+     */
+    resolveImportNode(node) {
+        // TSExternalModuleReference: module name in property "expression", otherwise "source"
+        const sourceNodeRaw = (node.type === NodeType.TSExternalModuleReference) ? node.expression : node.source;
+        // module name is expected to be a string literal
+        const isStringLiteral = (sourceNodeRaw?.type === NodeType.Literal) && (typeof sourceNodeRaw.value === "string");
+        return isStringLiteral ? new ImportNodeWrapper(sourceNodeRaw) : undefined;
+    }
+    /**
+     * Extracts an existing alias key, and resolves the module path of a module
+     * name.
+     *
+     * @param moduleName
+     *  The module name to extract an alias key from.
+     *
+     * @returns
+     *  A pair containing the alias key (empty string if no alias found), and
+     *  the resolved module path (passed module name if no alias found).
+     */
+    resolveAlias(moduleName) {
+        const [key, ...rest] = moduleName.split("/");
+        const aliasPath = (key && rest[0]) ? this.#aliasMap.get(key) : undefined;
+        const aliasKey = aliasPath ? key : "";
+        const modulePath = aliasPath ? posix.join(aliasPath, ...rest) : moduleName;
+        return [aliasKey, modulePath];
+    }
+    /**
+     * Returns whether the name of the module currently linted matches the
+     * specified glob patterns.
+     *
+     * @param patterns
+     *  The glob patterns to be matched against the current module name.
+     *
+     * @returns
+     *  Whether the current module name matches at least one glob pattern.
+     */
+    matchModuleName(patterns) {
+        return pm.isMatch(this.#moduleName, patterns);
+    }
+    /**
+     * Returns whether a source file exists for the specified module.
+     *
+     * @param modulePath
+     *  The resolved module path (alias key replaced with path).
+     *
+     * @returns
+     *  Whether a source file exists for the specified module.
+     */
+    fileExists(modulePath) {
+        // check modules with explicit extension
+        const resolvedPath = posix.join(this.#rootDir, modulePath);
+        if (extname(modulePath)) {
+            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.
+     *
+     * @param moduleName
+     *  The module name to be checked.
+     *
+     * @returns
+     *  Whether the passed module name is an installed NPM package.
+     */
+    packageExists(moduleName) {
+        this.#requireModule ??= createRequire(this.#configPath);
+        try {
+            this.#requireModule.resolve(moduleName);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
 }

package/doc/eslint/env/project.md

@@ -20,10 +20,9 @@ function project(options: EnvProjectOptions): 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. |
-| `modules` | `RuleNoInvalidModulesOptions` | `{}` | Configuration for the rule "env-project/no-invalid-modules": |
-| `modules.alias` | `Record<string, string>` | `{}` | Maps all alias prefixes to actual paths in the project (see below). |
-| `modules.external` | `string \| string[]` | `[]` | Specifies glob patterns for external modules (see below). |
-| `modules.packages` | `Record<string, EnvProjectPackage>` | `{}` | Allows to separate the source files into virtual packages (see below). |
+| `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). |
+| `hierarchy` | `Record<string, RuleNoInvalidHierarchyPackage>` | `{}` | 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`
@@ -43,10 +42,8 @@ export default [
   ...eslint.configure({ /* ... */ }),
   ...eslint.env.project({
     files: ["src/**/*.{js,ts}"],
-    modules: {
-      alias: {
-        "@": "src",
-      },
+    alias: {
+      "@": "src",
     },
   }),
 ]
@@ -57,7 +54,7 @@ export default [
 
 ### Option `external`
 
-- Type: `string | string[]`
+- Type: `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.
@@ -72,10 +69,8 @@ export default [
   ...eslint.configure({ /* ... */ }),
   ...eslint.env.project({
     files: ["src/**/*.{js,ts}"],
-    modules: {
-      alias: { "@": "src" },
-      external: ["virtual:*", "@/special/lib/**/*.js"],
-    },
+    alias: { "@": "src" },
+    external: ["virtual:*", "@/special/lib/**/*.js"],
   }),
 ]
 ```
@@ -83,19 +78,19 @@ export default [
 - 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`
+### Option `hierarchy`
 
-- Type: `Record<string, EnvProjectPackage>`
+- Type: `Record<string, RuleNoInvalidHierarchyPackage>`
 - 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`:
+Each key in the `hierarchy` record is the arbitrary unique name of a package. The record values must be objects satisfying the interface `RuleNoInvalidHierarchyPackage`:
 
 | Name | Type | Default | Description |
 | - | - | - | - |
-| `src` | `string\|string[]` | _required_ | Glob patterns selecting all source files that are part of the package. |
-| `extends` | `string\|string[]` | `[]` | Specifies the names of all packages (dictionary keys of the option `packages`) this package depends on. |
+| `files` | `string[]` | _required_ | Glob patterns selecting all source files that are part of the package. |
+| `extends` | `string\|string[]` | `[]` | Specifies the names of all packages (dictionary keys of the option `hierarchy`) 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).
@@ -110,21 +105,19 @@ export default [
   ...eslint.configure({ /* ... */ }),
   ...eslint.env.project({
     files: ["src/**/*.{js,ts}"],
-    modules: {
-      alias: { "@": "src" },
-      packages: {
-        base: {
-          src: ["@/base/**/*", "@/tools/**/*"],
-        },
-        debug: {
-          src: "@/debug/**/*",
-          extends: "base",
-          optional: true,
-        },
-        special: {
-          src: "@/my/special/**/*",
-          extends: ["base", "debug"],
-        },
+    alias: { "@": "src" },
+    hierarchy: {
+      base: {
+        files: ["@/base/**/*", "@/tools/**/*"],
+      },
+      debug: {
+        files: ["@/debug/**/*"],
+        extends: "base",
+        optional: true,
+      },
+      special: {
+        files: ["@/my/special/**/*"],
+        extends: ["base", "debug"],
       },
     },
   }),

package/package.json

@@ -1,7 +1,7 @@
 {
     "$schema": "https://json.schemastore.org/package",
     "name": "@open-xchange/linter-presets",
-    "version": "0.1.6",
+    "version": "0.1.7",
     "description": "Configuration presets for ESLint and StyleLint",
     "repository": {
         "url": "https://gitlab.open-xchange.com/fspd/npm-packages/linter-presets"

package/test/src/project1/file1.js

@@ -2,7 +2,7 @@
 // eslint-disable-next-line env-project/no-amd-module-directive
 /// <amd-module name="file1"/>
 
-// valid imports
+// valid static imports
 import "find-up";
 import "$/external/module";
 import "@/project1/generated";
@@ -11,16 +11,19 @@ import "@/project1/generated";
 import "invalid-package";
 // eslint-disable-next-line env-project/no-invalid-modules
 import "@/project1/invalid";
-// eslint-disable-next-line env-project/no-invalid-modules
+
+// eslint-disable-next-line env-project/no-invalid-hierarchy
 import "@/project2/file2";
-// eslint-disable-next-line env-project/no-invalid-modules
+// eslint-disable-next-line env-project/no-invalid-hierarchy
 import "@/project3/file3";
 
+// valid dynamic imports
 await import("find-up");
 await import("@/project1/generated");
 await import("@/project3/file3");
 
 // eslint-disable-next-line env-project/no-invalid-modules
 await import("invalid-package");
-// eslint-disable-next-line env-project/no-invalid-modules
+
+// eslint-disable-next-line env-project/no-invalid-hierarchy
 await import("@/project2/file2");