@markuplint/file-resolver 5.3.0 → 5.5.0

package/lib/cosmiconfig.js

@@ -1,10 +1,27 @@
+import fs from 'node:fs/promises';
 import path from 'node:path';
-import { ConfigParserError } from '@markuplint/parser-utils';
-import { cosmiconfig, defaultLoaders } from 'cosmiconfig';
+import { pathToFileURL } from 'node:url';
+import { inspect } from 'node:util';
+import { cosmiconfig, defaultLoaders, defaultLoadersSync } from 'cosmiconfig';
 import { jsonc } from 'jsonc';
-import { ConfigLoadError } from '@markuplint/shared';
+import { ConfigLoadError, isFatalError } from '@markuplint/shared';
 import { log } from './debug.js';
 const searchLog = log.extend('search');
+/**
+ * Fatal errors (see {@link isFatalError}) raised by markuplint's own code inside a loader. cosmiconfig
+ * gives every error a loader throws the path of the file, so {@link cacheConfigError} looks here to
+ * re-throw these as they are instead of reporting them as the configuration's fault.
+ */
+const ownErrors = new WeakSet();
+/**
+ * The `$import` target that {@link withImportCheck} could not read, by the error it threw.
+ */
+const unreadableImports = new WeakMap();
+/**
+ * The files whose change can fix a `ConfigLoadError` raised here, by the error; see
+ * {@link configLoadErrorFiles}.
+ */
+const filesOfErrors = new WeakMap();
 const jsoncLoader = (path, content) => {
     try {
         return jsonc.parse(content);
@@ -13,9 +30,179 @@ const jsoncLoader = (path, content) => {
         if (error instanceof Error && error.name === 'JSONError') {
             return defaultLoaders['noExt'](path, content);
         }
+        if (isFatalError(error) && error instanceof Error) {
+            ownErrors.add(error);
+        }
         throw error;
     }
 };
+/**
+ * Loads a JavaScript or TypeScript configuration file as cosmiconfig's `loadJs` does: `import()`
+ * of its real path, then `require()` when that fails, and the error of `import()` when `require()`
+ * fails only because the file is an ES module. Spelled out because `loadJs` reads `code` of what
+ * `require()` throws, which itself throws a `TypeError` when the configuration code throws `null`
+ * or `undefined`, and the value is lost.
+ *
+ * Unlike `loadJs`, what the configuration code itself threw while `import()` evaluated it is
+ * thrown as it is, without `require()`: see {@link isLoadingFailure}. Node.js's `require()` of
+ * such a module throws the same value again, but Deno's throws a new `Error` whose message is the
+ * stack of the original, which loses the value, its message and the location of the throw.
+ *
+ * A value the configuration code throws that is not an `Error` is thrown as one, with the value as
+ * its `cause`, so that it reaches {@link cacheConfigError} with the path of the file. cosmiconfig
+ * assigns `filepath` to what a loader throws, and that assignment itself throws a `TypeError` on a
+ * primitive, which loses both the value and the path.
+ *
+ * When cosmiconfig is upgraded, compare this with its `loadJs` (`dist/loaders.js`): how it
+ * imports the file, when it falls back to `require()` (`ERR_REQUIRE_ESM`), and whether it has
+ * started transpiling TypeScript itself.
+ *
+ * Neither `catch` is guarded by {@link isFatalError}: what is caught there was thrown by the
+ * user's code, or by the runtime loading it.
+ *
+ * @param filepath - The configuration file
+ * @param content - Its content, which `require()` does not use
+ * @returns The default export of the module, or `module.exports` of a CommonJS module
+ */
+const jsLoader = async (filepath, content) => {
+    try {
+        try {
+            const { href } = pathToFileURL(await fs.realpath(filepath));
+            const module = await import(href);
+            return module && typeof module === 'object' && 'default' in module ? module.default : undefined;
+        }
+        catch (importError) {
+            if (!isLoadingFailure(importError)) {
+                throw importError;
+            }
+            try {
+                return defaultLoadersSync['.js'](filepath, content);
+            }
+            catch (requireError) {
+                throw isRequireOfEsModule(requireError) ? importError : requireError;
+            }
+        }
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw error;
+        }
+        const message = typeof error === 'string' ? error : inspect(error, { breakLength: Infinity });
+        throw new Error(message, { cause: error });
+    }
+};
+/**
+ * Whether `import()` failed to load the module rather than the module's own code throwing: a
+ * `SyntaxError` (the file cannot be parsed as an ES module, but `require()` may take it as
+ * CommonJS, and reports the line of a syntax error that `import()` does not), or an error with a
+ * Node.js error code (`ERR_*`: a file extension or format that `import()` does not take, or a
+ * module that cannot be resolved). Anything else, an `Error` without such a code or a value that
+ * is not an `Error`, was thrown by the configuration code, and `require()` would only run it
+ * again.
+ *
+ * @param importError - What `import()` threw
+ * @returns `true` when `require()` is worth trying
+ */
+function isLoadingFailure(importError) {
+    return (importError instanceof SyntaxError ||
+        (importError instanceof Error &&
+            'code' in importError &&
+            typeof importError.code === 'string' &&
+            importError.code.startsWith('ERR_')));
+}
+/**
+ * Whether `require()` failed only because the file is an ES module, the same test as
+ * cosmiconfig's `loadJs`.
+ *
+ * @param requireError - What `require()` threw
+ * @returns `true` when the error of `import()` is the one to report
+ */
+function isRequireOfEsModule(requireError) {
+    return ((requireError instanceof Error && 'code' in requireError && requireError.code === 'ERR_REQUIRE_ESM') ||
+        (requireError instanceof SyntaxError &&
+            requireError.toString().includes('Cannot use import statement outside a module')));
+}
+/**
+ * Wraps `loader` so that a `$import` target that cannot be read fails while the file that
+ * declares it is being loaded. cosmiconfig reads the targets itself after the loader has
+ * returned, and fails without `filepath` there; worse, its search takes a target that does not
+ * exist (or ENOENT's kin: EACCES, EISDIR, ENOTDIR) for a search place without a file, and passes
+ * the declaring file over in silence, so the target would be linted with another configuration.
+ * Thrown from inside the loader, the failure carries the path of the declaring file (see
+ * {@link cacheConfigError}).
+ *
+ * A target that is not a string, the file itself, or a cycle is left to cosmiconfig, which
+ * reports it with the path in its message (see {@link importErrorPath}).
+ *
+ * Each target is opened and one byte of it read, which fails as cosmiconfig's `readFile` of it
+ * would (a directory fails at the read, not at the open), without reading it in full twice. A
+ * fatal error of this check is markuplint's own, and is recorded in {@link ownErrors}.
+ *
+ * @param loader - The loader of one format
+ * @returns The loader, checking the `$import` of what it loaded
+ */
+function withImportCheck(loader) {
+    return async (filepath, content) => {
+        const loaded = await loader(filepath, content);
+        try {
+            const imports = importsOf(filepath, loaded);
+            await Promise.all(imports
+                .filter(importPath => typeof importPath === 'string')
+                .map(importPath => probeImport(path.resolve(path.dirname(filepath), importPath), importPath)));
+        }
+        catch (error) {
+            if (isFatalError(error) && error instanceof Error) {
+                ownErrors.add(error);
+            }
+            throw error;
+        }
+        return loaded;
+    };
+}
+/**
+ * The `$import` entries of what a loader loaded, taken from where cosmiconfig takes them: the
+ * `markuplint` field of a package file (`package.json`, `package.yaml` and the like, whatever the
+ * extension), or the whole of any other file.
+ *
+ * @param filepath - The file the loader was given
+ * @param loaded - What the loader returned
+ * @returns The entries, of whatever type; empty when there is no `$import`
+ */
+function importsOf(filepath, loaded) {
+    const own = path.basename(filepath, path.extname(filepath)) === 'package'
+        ? loaded && typeof loaded === 'object' && 'markuplint' in loaded
+            ? loaded.markuplint
+            : undefined
+        : loaded;
+    if (!own || typeof own !== 'object' || !('$import' in own)) {
+        return [];
+    }
+    return Array.isArray(own.$import) ? own.$import : [own.$import];
+}
+/**
+ * Fails when `target` cannot be read; see {@link withImportCheck}.
+ *
+ * @param target - The absolute path of a `$import` target
+ * @param importPath - The entry as written, for the message
+ */
+async function probeImport(target, importPath) {
+    let handle;
+    try {
+        handle = await fs.open(target, 'r');
+        await handle.read(Buffer.alloc(1), 0, 1, 0);
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        const cannotImport = new Error(`Cannot import ${importPath}: ${error instanceof Error ? error.message : String(error)}`, { cause: error });
+        unreadableImports.set(cannotImport, target);
+        throw cannotImport;
+    }
+    finally {
+        await handle?.close();
+    }
+}
 const explorer = cosmiconfig('markuplint', {
     searchPlaces: [
         'package.json',
@@ -35,10 +222,15 @@ const explorer = cosmiconfig('markuplint', {
         'markuplint.config.jsonc',
     ],
     loaders: {
-        noExt: jsoncLoader,
-        '.jsonc': jsoncLoader,
+        noExt: withImportCheck(jsoncLoader),
+        '.jsonc': withImportCheck(jsoncLoader),
+        '.json': withImportCheck(defaultLoaders['.json']),
+        '.yaml': withImportCheck(defaultLoaders['.yaml']),
+        '.yml': withImportCheck(defaultLoaders['.yml']),
+        ...Object.fromEntries(['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].map(ext => [ext, withImportCheck(jsLoader)])),
     },
-    searchStrategy: 'project',
+    // Not 'project', which stops at the first `package.json`; `search()` walks the ancestors itself.
+    searchStrategy: 'none',
 });
 /**
  * Clears the shared `cosmiconfig` explorer's own internal search/load caches.
@@ -51,24 +243,99 @@ const explorer = cosmiconfig('markuplint', {
 export function clearExplorerCache() {
     explorer.clearCaches();
 }
+/**
+ * Spelled out because `search()` needs the ancestors one directory at a time; see there for why
+ * none of cosmiconfig's own search strategies fits.
+ *
+ * @param dir - The directory to start from, which is yielded first
+ */
+function* ancestorDirs(dir) {
+    let current = path.resolve(dir);
+    while (true) {
+        yield current;
+        const parent = path.dirname(current);
+        if (parent === current) {
+            return;
+        }
+        current = parent;
+    }
+}
+/**
+ * Whether `dir` does not exist: ENOENT, or ENOTDIR when one of its ancestors is a regular file
+ * (POSIX; Windows reports that as ENOENT). Checked before cosmiconfig is asked, as its own
+ * directory check takes only ENOENT for missing and throws on ENOTDIR, and as a directory it
+ * never sees leaves no entry in its search cache: a configuration file created later together
+ * with the directory is found without `clearExplorerCache()`.
+ *
+ * Any other `stat` failure (EACCES, for one) is reported like a configuration file that cannot be
+ * loaded, as the walk cannot tell whether that directory holds the nearest configuration.
+ *
+ * @param dir - The directory to examine
+ * @param filePath - The target file, named in the error report
+ */
+async function isMissingDir(dir, filePath) {
+    try {
+        await fs.stat(dir);
+        return false;
+    }
+    catch (error) {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        if (error instanceof Error && 'code' in error && (error.code === 'ENOENT' || error.code === 'ENOTDIR')) {
+            return true;
+        }
+        return cacheConfigError(dir, filePath, true)(error);
+    }
+}
+/**
+ * Searches for a configuration file in the directory of `filePath` and in each ancestor
+ * directory up to the file system root, nearest first.
+ *
+ * The walk is done here and not by cosmiconfig's `searchStrategy: 'project'`: that strategy
+ * stops at the first directory that has a `package.json`, which hides a configuration file at a
+ * monorepo root from every file inside a package, while the documented behavior is that the
+ * search goes upward from the target file's directory (https://markuplint.dev/docs/configuration).
+ * `searchStrategy: 'global'` is no substitute: it also searches the OS-level configuration
+ * directory, and that cannot be turned off.
+ *
+ * A directory that has a `package.json` or `package.yaml` does not end the walk: a `package.json`
+ * without a `markuplint` field is not a configuration file, and a `package.yaml` never is, as it
+ * is not among the search places. A directory that does not exist, the target's own included,
+ * is passed over (see {@link isMissingDir}). An empty configuration is treated like no result
+ * and the walk continues. A configuration file that cannot be loaded, at any level, makes the
+ * search throw instead of being skipped. There is no upper bound below the file system root, so a
+ * configuration file in a directory outside the project applies when nothing nearer exists.
+ *
+ * @template T - The type of the configuration object
+ * @param filePath - The path of the target file; the search starts from its directory
+ * @param cacheClear - Whether to clear the explorer's caches before searching
+ * @returns The path and content of the nearest configuration file, or `null` if none was found
+ */
 export async function search(filePath, cacheClear) {
     if (cacheClear) {
         explorer.clearCaches();
     }
-    const dir = path.dirname(filePath);
-    searchLog('Search dir: %s', dir);
-    const result = await explorer.search(dir).catch(cacheConfigError(dir, filePath));
-    searchLog('Search result: %O', result);
-    if (!result || result.isEmpty) {
-        return null;
+    for (const dir of ancestorDirs(path.dirname(filePath))) {
+        searchLog('Search dir: %s', dir);
+        if (await isMissingDir(dir, filePath)) {
+            searchLog('Missing: %s', dir);
+            continue;
+        }
+        const result = await explorer.search(dir).catch(cacheConfigError(dir, filePath, true));
+        searchLog('Search result: %O', result);
+        if (!result || result.isEmpty) {
+            continue;
+        }
+        const config = result.config;
+        return {
+            filePath: result.filepath,
+            config: config && typeof config === 'object' && 'default' in config && typeof config.default === 'object'
+                ? config.default
+                : config,
+        };
     }
-    const config = result.config;
-    return {
-        filePath: result.filepath,
-        config: config && typeof config === 'object' && 'default' in config && typeof config.default === 'object'
-            ? config.default
-            : config,
-    };
+    return null;
 }
 export async function load(filePath, cacheClear, referrer) {
     if (cacheClear) {
@@ -86,19 +353,175 @@ export async function load(filePath, cacheClear, referrer) {
             : config,
     };
 }
-function cacheConfigError(fileOrDirPath, referrer) {
-    return (reason) => {
-        if (reason instanceof Error) {
-            switch (reason.name) {
-                case 'YAMLException': {
-                    throw new ConfigParserError(reason.message, {
-                        // @ts-ignore
-                        filePath: reason.filepath ?? fileOrDirPath,
-                    });
-                }
-            }
-            throw new ConfigLoadError(reason.message, fileOrDirPath, referrer);
+/**
+ * Converts a failure of cosmiconfig, or of the `stat` in {@link isMissingDir}, into the error
+ * markuplint reports: a `ConfigLoadError`, whatever the format of the file. A file that cannot
+ * be parsed is one, YAML included, as `MLEngine` fails the target for it like for any other
+ * configuration that cannot be loaded.
+ *
+ * cosmiconfig sets `filepath` on what a loader throws (a file that cannot be parsed or imported,
+ * or whose `$import` target cannot be read, see {@link withImportCheck}; a value the
+ * configuration code throws that is not an `Error` is one by then, see {@link jsLoader}). That
+ * path, not `fileOrDirPath`, is the one reported: a search walks up through the ancestors of the
+ * target, so the directory being searched can be far from the target, and only the path tells
+ * the user which configuration file to fix. The message names it as well, as `MLEngine` shows
+ * the message alone, unless cosmiconfig's JSON or YAML loader already began it with the path.
+ *
+ * An error without `filepath` is one cosmiconfig raises outside a loader, or one from a
+ * directory that cannot be examined. Of the former, an invalid `$import` (not a string, the file
+ * itself, a cycle) names the file that declares it in the message, and is reported with that path
+ * (see {@link importErrorPath}); any other is reported with `fileOrDirPath`. Either keeps its own
+ * message.
+ *
+ * When the configuration code throws, the path is followed by the location in that file nearest
+ * the throw (see {@link stackLocation}), so that the user can open it at the failing statement.
+ * The original error is kept as the `cause`.
+ *
+ * Only a fatal error that markuplint's own code raised inside a loader ({@link ownErrors}) is
+ * re-thrown as it is. Every other error a loader throws comes from the user's configuration code,
+ * or from parsing the user's file with `JSON.parse` or js-yaml, so a `SyntaxError` or a
+ * `TypeError` there is the configuration's fault, not a broken invariant of markuplint. An error
+ * without `filepath` is not guarded either: it comes from cosmiconfig or from the file system,
+ * not from markuplint, and fails the target as a configuration that cannot be loaded.
+ *
+ * What {@link configLoadErrorFiles} returns for the error is recorded here: the file reported,
+ * and the `$import` target that could not be read; nothing when a directory is reported.
+ *
+ * @param fileOrDirPath - The configuration file given to `load()`, or the directory being searched
+ * @param referrer - The file whose configuration is being loaded
+ * @param isDir - Whether `fileOrDirPath` is a directory
+ * @returns A handler for the rejection, which always throws
+ */
+function cacheConfigError(fileOrDirPath, referrer, isDir = false) {
+    return async (reason) => {
+        if (!(reason instanceof Error) || ownErrors.has(reason)) {
+            throw reason;
         }
-        throw reason;
+        const filepath = 'filepath' in reason && typeof reason.filepath === 'string' ? reason.filepath : null;
+        if (!filepath) {
+            const declaring = importErrorPath(reason.message);
+            const error = new ConfigLoadError(reason.message, declaring ?? fileOrDirPath, referrer, { cause: reason });
+            filesOfErrors.set(error, declaring == null && isDir ? [] : [error.filePath]);
+            throw error;
+        }
+        // The parser's report on the lines after the path ends with a code frame for YAML; a newline
+        // keeps the ` in <referrer>` that `ConfigLoadError` appends off its last line.
+        const message = isPrefixedByLoader(reason.message, filepath)
+            ? `${reason.message}\n`
+            : `Failed to load ${filepath}${await locate(reason, filepath)}: ${reason.message}`;
+        const error = new ConfigLoadError(message, filepath, referrer, { cause: reason });
+        const unreadable = unreadableImports.get(reason);
+        filesOfErrors.set(error, unreadable == null ? [filepath] : [unreadable, filepath]);
+        throw error;
     };
 }
+/**
+ * The files whose change can fix `error`, for a caller to watch or to list among the files a
+ * configuration depends on: the file it names and, when that file's `$import` target could not
+ * be read, the target, which may not exist yet. Nothing when it names a directory that a search
+ * could not examine. For a `ConfigLoadError` raised elsewhere (a preset, a module), what it names.
+ *
+ * @param error - A `ConfigLoadError`
+ * @returns The absolute paths of the files, the `$import` target first; or what `error` names
+ */
+export function configLoadErrorFiles(error) {
+    return filesOfErrors.get(error) ?? [error.filePath];
+}
+/**
+ * Whether `message` begins as cosmiconfig's JSON and YAML loaders begin the message of the error
+ * they re-throw (`JSON Error in <path>:` / `YAML Error in <path>:`). Checked as a prefix rather
+ * than as any occurrence of the path, which an error that the configuration code throws can
+ * contain too.
+ *
+ * @param message - The message of the error a loader threw
+ * @param filepath - The configuration file the loader was given
+ * @returns `true` when the message already names the file
+ */
+function isPrefixedByLoader(message, filepath) {
+    return message.startsWith(`JSON Error in ${filepath}:`) || message.startsWith(`YAML Error in ${filepath}:`);
+}
+/**
+ * The file that declares an invalid `$import`, read from the message of the error that
+ * cosmiconfig's `validateImports` throws without `filepath`: `Self-import detected in <path>`,
+ * `<path>: Key $import must contain a string or a list of strings`, or `Circular import
+ * detected:` followed by the numbered files of the cycle, the last of which repeats an earlier
+ * one, so the one before the last declares the `$import` that closes it. When cosmiconfig is
+ * upgraded, compare these with its `ExplorerBase.validateImports`; a message that matches none
+ * leaves the error reported with the directory or file it was loaded for. The specs of these
+ * cases in `config-provider.spec.ts` run against the installed cosmiconfig, so a rewording fails
+ * them.
+ *
+ * @param message - The message of an error without `filepath`
+ * @returns The path, or `null` when the message is none of these
+ */
+function importErrorPath(message) {
+    const self = /^Self-import detected in (.+)$/.exec(message);
+    if (self) {
+        return self[1];
+    }
+    const notString = /^(.+): Key \$import must contain a string or a list of strings$/.exec(message);
+    if (notString) {
+        return notString[1];
+    }
+    if (message.startsWith('Circular import detected:\n')) {
+        const entries = message.split('\n').slice(1);
+        return /^\d+\. (.+)$/.exec(entries.at(-2) ?? '')?.[1] ?? null;
+    }
+    return null;
+}
+/**
+ * The location in `filepath` at which `error` was thrown, for {@link cacheConfigError}.
+ *
+ * cosmiconfig imports the real path of a JavaScript configuration file, so its frames name the
+ * real path when `filepath` goes through a symbolic link; both are looked for.
+ *
+ * Reading `stack` can throw in Deno when source map resolution meets an invalid mapping (see
+ * `MLEngine`'s `#exec`), and `realpath` can fail if the file has gone since it was loaded. Either
+ * failure leaves the error named by its path alone; the error being reported is the one that
+ * matters, so neither is re-thrown and neither is guarded by {@link isFatalError}. Only those two
+ * are caught: a failure of {@link stackLocation} is markuplint's own.
+ *
+ * @param error - The error a loader threw
+ * @param filepath - The configuration file the loader was given
+ * @returns What {@link stackLocation} returns
+ */
+async function locate(error, filepath) {
+    let stack;
+    try {
+        stack = error.stack ?? '';
+    }
+    catch (stackError) {
+        searchLog('Cannot read the stack of the error in %s: %O', filepath, stackError);
+        return '';
+    }
+    // The message heads the stack, and can name the file with a line of its own.
+    const header = `${error.name}: ${error.message}`;
+    const frames = stack.startsWith(header) ? stack.slice(header.length) : stack;
+    const realpath = await fs.realpath(filepath).catch(() => filepath);
+    return stackLocation(frames, [filepath, realpath]);
+}
+/**
+ * Finds the location nearest the top of `stack` that names one of `filePaths`, by its path (a
+ * CommonJS module) or by its `file:` URL (an ES module): a frame, `<path>:<line>:<column>`, or
+ * the header that Node.js puts above a `SyntaxError` in a CommonJS module, `<path>:<line>`. A
+ * `SyntaxError` in an ES module has neither. A Windows path is also looked for with forward
+ * slashes (`C:/p/…`), as a module runner such as Vitest names the module it evaluates.
+ *
+ * A path only matches as a whole, at the start of a line or after whitespace or `(`, so that
+ * another file whose path ends with the same characters does not.
+ *
+ * @param stack - The `stack` of an error
+ * @param filePaths - Absolute paths of the same file
+ * @returns `:<line>:<column>`, `:<line>` for a header, or an empty string when there is neither
+ */
+export function stackLocation(stack, filePaths) {
+    const forms = [
+        ...new Set(filePaths.flatMap(filePath => [filePath, filePath.replaceAll('\\', '/'), pathToFileURL(filePath).href])),
+    ];
+    const location = new RegExp(String.raw `(?:^|[\s(])(?:${forms.map(form => RegExp.escape(form)).join('|')}):(\d+)(?::(\d+))?`, 'm');
+    const match = location.exec(stack);
+    if (!match) {
+        return '';
+    }
+    return match[2] == null ? `:${match[1]}` : `:${match[1]}:${match[2]}`;
+}

package/lib/general-import.d.ts

@@ -1 +1,19 @@
+/**
+ * Imports the module that a configuration names (a configuration to `extends`, a parser, a
+ * plugin, the data of `pretenders`) and returns what it exports: the default export when there is
+ * one, the namespace otherwise. Whatever cannot be imported, for whatever reason, yields `null`,
+ * as the callers report a missing module in their own terms; the reason goes to the debug log.
+ *
+ * A subpath of a package that its `exports` map does not expose is turned into the absolute path
+ * of the file first (see {@link resolvePackageSubpath}), as `import()` refuses it. A JSON module
+ * is taken by {@link importModule} through `require()`, so no `.json` file is read by hand: what
+ * `require()` takes as JSON, a byte order mark included, is what is accepted.
+ *
+ * The result is cached by specifier for the life of the process, `null` included; `import()`
+ * itself keeps a module for as long, so a fresh read is not to be had either way.
+ *
+ * @template T - What the module exports
+ * @param name - A bare specifier, with a subpath or not, or an absolute path
+ * @returns What the module exports, or `null` when it cannot be imported
+ */
 export declare function generalImport<T>(name: string): Promise<T | null>;

package/lib/general-import.js

@@ -1,15 +1,33 @@
-import fs from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
 import { isFatalError } from '@markuplint/shared';
 import { resolve } from 'import-meta-resolve';
 import { log } from './debug.js';
-import { fromFileURL, toFileURL } from './path-utils.js';
+import { importModule } from './import-module.js';
+import { fromFileURL, isRelativePath, toFileURL } from './path-utils.js';
 const gLog = log.extend('general-import');
 const gLogSuccess = gLog.extend('success');
 const gLogError = gLog.extend('error');
 const cache = new Map();
 const require = createRequire(import.meta.url);
+/**
+ * Imports the module that a configuration names (a configuration to `extends`, a parser, a
+ * plugin, the data of `pretenders`) and returns what it exports: the default export when there is
+ * one, the namespace otherwise. Whatever cannot be imported, for whatever reason, yields `null`,
+ * as the callers report a missing module in their own terms; the reason goes to the debug log.
+ *
+ * A subpath of a package that its `exports` map does not expose is turned into the absolute path
+ * of the file first (see {@link resolvePackageSubpath}), as `import()` refuses it. A JSON module
+ * is taken by {@link importModule} through `require()`, so no `.json` file is read by hand: what
+ * `require()` takes as JSON, a byte order mark included, is what is accepted.
+ *
+ * The result is cached by specifier for the life of the process, `null` included; `import()`
+ * itself keeps a module for as long, so a fresh read is not to be had either way.
+ *
+ * @template T - What the module exports
+ * @param name - A bare specifier, with a subpath or not, or an absolute path
+ * @returns What the module exports, or `null` when it cannot be imported
+ */
 export async function generalImport(name) {
     if (cache.has(name)) {
         return cache.get(name);
@@ -33,45 +51,21 @@ export async function generalImport(name) {
         if (importPath !== name) {
             gLog('Converted to file URL: %s', importPath);
         }
-        const imported = await import(importPath);
-        const mod = imported?.default ?? imported ?? null;
+        const imported = await importModule(importPath);
+        // A JSON module whose value is `null` is `null`, as a file with nothing in it; `??` would
+        // hand the namespace over instead.
+        const mod = (('default' in imported ? imported.default : imported) ?? null);
         gLogSuccess('Success by import("%s"): %O', importPath, mod);
         cache.set(name, mod);
         return mod;
     }
     catch (error) {
-        // NOTE: `isFatalError()` is intentionally NOT applied at this catch
-        // boundary. `await import()` / `require()` invoke third-party module
-        // code, so any Tier-1-shaped error (TypeError / SyntaxError / etc.)
-        // at this point may originate from inside the imported module and
-        // not from markuplint's own code — we cannot distinguish the two.
-        // The Tier 1 classification (see `isFatalError()` in
-        // `@markuplint/shared`) only covers errors raised by markuplint's
-        // own code, which excludes third-party import failures (e.g. Node 22+ removing
-        // import assertion syntax, or bun's stricter ESM parser). Treating
-        // every error as a recoverable null-return is the correct policy
-        // here; callers (config / parser / plugin loaders) decide how to
-        // surface the missing module.
-        if (
-        // @ts-ignore
-        'code' in error &&
-            // @ts-ignore
-            error.code === 'ERR_IMPORT_ASSERTION_TYPE_MISSING') {
-            try {
-                const mod = require(name) ?? null;
-                gLogSuccess('Success by require("%s"): %O', name, mod);
-                cache.set(name, mod);
-                return mod;
-            }
-            catch (error) {
-                if (error instanceof Error && /^parse failure/i.test(error.message)) {
-                    gLogError('Error in `createRequire(import.meta.url)()`: %O', error);
-                    cache.set(name, null);
-                    return null;
-                }
-                gLogError('Error in generalImport: %O', error);
-            }
-        }
+        // `isFatalError()` is intentionally NOT applied at this catch: `importModule()` runs
+        // `import()`, which evaluates third-party module code, so a Tier-1-shaped error here
+        // (TypeError / SyntaxError / etc.) may come from the imported module or from the runtime's
+        // loader rather than from markuplint's own code, and the two cannot be told apart. Every
+        // error is a recoverable `null`; the callers (config / parser / plugin loaders) decide how
+        // to surface the missing module.
         if (error instanceof Error) {
             const { filePath, packageName } = /Missing\s"(?<filePath>[^"]+)"\sspecifier\sin\s"(?<packageName>[^"]+)"\spackage/.exec(error.message)
                 ?.groups ?? {};
@@ -86,18 +80,6 @@ export async function generalImport(name) {
                 return result;
             }
         }
-        if (path.isAbsolute(name) && name.endsWith('.json')) {
-            try {
-                const file = await fs.readFile(name, 'utf8');
-                const json = JSON.parse(file);
-                gLogSuccess('Success by readFile("%s") and JSON.parse: %O', name, json);
-                cache.set(name, json);
-                return json;
-            }
-            catch (readError) {
-                gLogError('Error in readFile("%s"): %O', name, readError);
-            }
-        }
         gLogError('Error in `import()`: %O', error);
         cache.set(name, null);
         return null;
@@ -111,7 +93,7 @@ export async function generalImport(name) {
  * - The package cannot be found at all
  */
 function resolvePackageSubpath(name) {
-    if (path.isAbsolute(name) || name.startsWith('.')) {
+    if (path.isAbsolute(name) || isRelativePath(name)) {
         return null;
     }
     const packageName = name.startsWith('@') ? name.split('/').slice(0, 2).join('/') : name.split('/')[0];