@markuplint/file-resolver 5.4.0 → 5.5.0

package/CHANGELOG.md

@@ -3,6 +3,18 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.5.0](https://github.com/markuplint/markuplint/compare/v5.4.0...v5.5.0) (2026-11-10)
+
+### Bug Fixes
+
+* **file-resolver:** do not report a config shared by two extends paths as circular ([8594a37](https://github.com/markuplint/markuplint/commit/8594a373feda1a2f869702b6b16d619d156814c4)), closes [#4552](https://github.com/markuplint/markuplint/issues/4552)
+* **file-resolver:** do not swallow errors other than InvalidSelectorError in validation ([821a661](https://github.com/markuplint/markuplint/commit/821a66170e84537c57d826133bdf486c6276f524))
+* **file-resolver:** load @markuplint/pretenders only when a configuration needs it ([32ee579](https://github.com/markuplint/markuplint/commit/32ee579e4b43cf18ba9787f173796c44966c3b40))
+* **file-resolver:** read the report of a JSON module before the code of a missing one ([95e4869](https://github.com/markuplint/markuplint/commit/95e4869c9be3bd53f853e5a99830514bfec5a51b))
+* **file-resolver:** resolve a value spelled as a path from the configuration's directory ([3fbfeca](https://github.com/markuplint/markuplint/commit/3fbfeca83b29ba852709c50667d60ca28f1dfce6)), closes [#4459](https://github.com/markuplint/markuplint/issues/4459)
+* **file-resolver:** take a JSON module through require() when import() refuses it ([15303ba](https://github.com/markuplint/markuplint/commit/15303baae4e56ac26d1e3eb4522230bae1d93efe))
+
+
 # [5.4.0](https://github.com/markuplint/markuplint/compare/v5.3.0...v5.4.0) (2026-10-29)
 
 ### Bug Fixes

package/lib/config-provider.d.ts

@@ -59,13 +59,27 @@ export declare class ConfigProvider {
     /**
      * Recursively loads a configuration and all its `extends` dependencies.
      *
+     * A `CircularReferenceError` is reported only for a config that extends itself, directly or
+     * indirectly. A config reached through more than one `extends` path is loaded once and is not
+     * an error.
+     *
      * @param key - The config file path or module name to load
      * @param cache - Whether to use cached results
      * @param referrer - The file path of the config that referenced this key
-     * @param depth - Current recursion depth (for circular reference detection)
      * @returns A set of loaded config keys and any errors encountered
      */
-    recursiveLoad(key: string, cache: boolean, referrer: string, depth?: number): Promise<{
+    recursiveLoad(key: string, cache: boolean, referrer: string): Promise<{
+        stack: Set<string>;
+        errs: Error[];
+    }>;
+    /**
+     * @deprecated Remove the `depth` argument: it is ignored, and the overload will be removed in v6.
+     * @param key - The config file path or module name to load
+     * @param cache - Whether to use cached results
+     * @param referrer - The file path of the config that referenced this key
+     * @param depth - Ignored
+     */
+    recursiveLoad(key: string, cache: boolean, referrer: string, depth: number): Promise<{
         stack: Set<string>;
         errs: Error[];
     }>;
@@ -92,7 +106,10 @@ export declare class ConfigProvider {
      * right before calling this) — see #4015.
      *
      * @param targetFile - The file being linted
-     * @param names - Config file paths or module names to merge
+     * @param names - Config file paths or module names to merge. A key of a configuration already
+     * stored (by {@link set} or {@link search}) is taken as it is; any other name is resolved as a
+     * value of `extends` is, from the working directory: a module name stays, a path becomes
+     * absolute
      * @param cache - Whether to reuse already-loaded/cached entries
      * @returns The fully resolved configuration set including plugins and errors
      */

package/lib/config-provider.js

@@ -2,7 +2,7 @@ import path from 'node:path';
 import { mergeConfig, rebaseHandWrittenPretenderFilePath } from '@markuplint/ml-config';
 import { ConfigParserError } from '@markuplint/parser-utils';
 import { InvalidSelectorError, createSelector } from '@markuplint/selector';
-import { nonNullableFilter, toNoEmptyStringArrayFromStringOrArray, ConfigLoadError } from '@markuplint/shared';
+import { nonNullableFilter, toNoEmptyStringArrayFromStringOrArray, ConfigLoadError, isFatalError, } from '@markuplint/shared';
 import { clearAutoLoadRulesCache } from './auto-load-rules.js';
 import { load as loadConfig, search, clearExplorerCache, configLoadErrorFiles } from './cosmiconfig.js';
 import { log } from './debug.js';
@@ -12,6 +12,7 @@ import { isPluginModuleName } from './is-plugin-module-name.js';
 import { isPresetModuleName } from './is-preset-module-name.js';
 import { moduleExists } from './module-exists.js';
 import { relPathToNameOrAbsPath } from './path-to-abs-or-name.js';
+import { resolveNameOrAbsPath } from './resolve-name-or-abs-path.js';
 import { cacheClear, resolvePlugins } from './resolve-plugins.js';
 import { fileExists, uuid } from './utils.js';
 const cpLog = log.extend('config-provider');
@@ -32,7 +33,6 @@ const KEY_SEPARATOR = '__ML_CONFIG_MERGE__';
 export class ConfigProvider {
     #cache = new Map();
     #held = new Set();
-    #recursiveLoadKeyAndDepth = new Map();
     #store = new Map();
     /**
      * Stabilizes {@link set}'s auto-generated key for an inline config object
@@ -108,26 +108,34 @@ export class ConfigProvider {
             release();
         }
     }
+    async recursiveLoad(key, cache, referrer, depth) {
+        return await this.#recursiveLoad(key, cache, referrer, new Set(), new Set());
+    }
     /**
-     * Recursively loads a configuration and all its `extends` dependencies.
+     * A config is circular only when it is its own ancestor on the current `extends` path
+     * (`ancestors`). Reaching the same config through two different paths (a diamond, e.g. two
+     * presets that extend the same sub-presets) is not a cycle, however deep each path is, so
+     * comparing depths cannot tell the two apart (#4552).
      *
-     * @param key - The config file path or module name to load
-     * @param cache - Whether to use cached results
-     * @param referrer - The file path of the config that referenced this key
-     * @param depth - Current recursion depth (for circular reference detection)
-     * @returns A set of loaded config keys and any errors encountered
+     * `visited` holds every key already walked in this top-level call. A key met again is skipped:
+     * its keys are already in the result and its errors, circular ones included, were already
+     * reported once. Without it the walk repeats once per path, which grows exponentially with
+     * stacked diamonds, and reports the same error once per path. State lives in the arguments,
+     * not on the instance, so concurrent calls do not see each other.
      */
-    async recursiveLoad(key, cache, referrer, depth = 1) {
+    async #recursiveLoad(key, cache, referrer, ancestors, visited) {
         const stack = new Set();
         const errs = [];
-        const ancestorDepth = this.#recursiveLoadKeyAndDepth.get(key);
-        if (ancestorDepth != null && ancestorDepth < depth) {
+        if (ancestors.has(key)) {
             return {
                 stack,
                 errs: [new CircularReferenceError(`Circular reference detected: ${key}`)],
             };
         }
-        this.#recursiveLoadKeyAndDepth.set(key, depth);
+        if (visited.has(key)) {
+            return { stack, errs };
+        }
+        visited.add(key);
         let config = this.#store.get(key);
         if (!config) {
             config = await this.#load(key, cache, referrer);
@@ -151,12 +159,18 @@ export class ConfigProvider {
         }
         const depKeys = config.extends === null ? null : toNoEmptyStringArrayFromStringOrArray(config.extends);
         if (depKeys) {
-            for (const depKey of depKeys) {
-                const keys = await this.recursiveLoad(depKey, cache, key, depth + 1);
-                for (const key of keys.stack) {
-                    stack.add(key);
+            ancestors.add(key);
+            try {
+                for (const depKey of depKeys) {
+                    const keys = await this.#recursiveLoad(depKey, cache, key, ancestors, visited);
+                    for (const loadedKey of keys.stack) {
+                        stack.add(loadedKey);
+                    }
+                    errs.push(...keys.errs);
                 }
-                errs.push(...keys.errs);
+            }
+            finally {
+                ancestors.delete(key);
             }
         }
         stack.add(key);
@@ -185,12 +199,17 @@ export class ConfigProvider {
      * right before calling this) — see #4015.
      *
      * @param targetFile - The file being linted
-     * @param names - Config file paths or module names to merge
+     * @param names - Config file paths or module names to merge. A key of a configuration already
+     * stored (by {@link set} or {@link search}) is taken as it is; any other name is resolved as a
+     * value of `extends` is, from the working directory: a module name stays, a path becomes
+     * absolute
      * @param cache - Whether to reuse already-loaded/cached entries
      * @returns The fully resolved configuration set including plugins and errors
      */
     async resolve(targetFile, names, cache = true) {
-        const keys = names.filter(nonNullableFilter);
+        const keys = await Promise.all(names
+            .filter(nonNullableFilter)
+            .map(name => (this.#store.has(name) ? name : resolveNameOrAbsPath(process.cwd(), name))));
         const key = keys.join(KEY_SEPARATOR);
         let baseConfigSet = this.#cache.get(key);
         if (!baseConfigSet) {
@@ -397,7 +416,6 @@ export class ConfigProvider {
         const resolvedKeys = new Set();
         const errs = [];
         for (const key of keys) {
-            this.#recursiveLoadKeyAndDepth.clear();
             const keySet = await this.recursiveLoad(key, cache, referrer);
             for (const k of keySet.stack) {
                 resolvedKeys.add(k);
@@ -442,12 +460,16 @@ export class ConfigProvider {
                         createSelector(rule.selector);
                     }
                     catch (error) {
-                        if (error instanceof InvalidSelectorError) {
-                            errors.push(new ConfigParserError(error.message, {
-                                filePath,
-                                raw: rule.selector,
-                            }));
+                        // Anything but an `InvalidSelectorError` is not a fault of the selector string the user wrote
+                        // (a bug, or an argument that only an extended pseudo-class reads), so it must propagate
+                        // instead of being reported as a configuration error.
+                        if (isFatalError(error) || !(error instanceof InvalidSelectorError)) {
+                            throw error;
                         }
+                        errors.push(new ConfigParserError(error.message, {
+                            filePath,
+                            raw: rule.selector,
+                        }));
                     }
                 }
             }

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];

package/lib/import-module.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `import()` that takes a JSON module as one. Node.js and Deno load a JSON module through
+ * `import()` only with the import attribute `type: 'json'` (Bun takes it either way), and a
+ * module that a configuration names can be one, a configuration to `extends` or the data of
+ * `pretenders`, with or without the `.json` extension, as the `exports` map of a package can
+ * redirect a specifier. The attribute cannot be given up front, as a `.json` specifier can be
+ * redirected to a JavaScript module the same way, and the attribute would then be rejected; and
+ * Deno rejects a dynamic `import()` with the attribute as it rejects one without. So the
+ * specifier is imported as it is, and when the runtime reports a JSON module without the
+ * attribute ({@link isJsonWithoutAttribute}), or the `.json` extension says so, it is
+ * `require()`d instead: CommonJS takes a JSON module as it is on every runtime, a bare specifier
+ * and a path alike, and what it returns is handed over as the default export, the shape
+ * `import()` gives a JSON module. Any other failure of `import()` is thrown as it is, as that is
+ * what the callers read (a package that is not installed, a subpath that `exports` does not
+ * expose), and `require()` would only run the module's code again. The report is read before the
+ * code of a missing module, as Deno attaches that code to the report as well; the code decides
+ * only for a `.json` specifier that the runtime did not report as JSON.
+ *
+ * The `catch` is not guarded by `isFatalError()`: the runtimes report the missing attribute with
+ * a `TypeError`, which the guard would re-throw before the retry.
+ *
+ * @param specifier - What `import()` takes: a bare specifier, a `file:` URL, or an absolute path
+ *   as `moduleExists()` passes it (a Windows drive path fails here and is left to its
+ *   `require.resolve()`)
+ * @returns The module namespace that `import()` resolves to, or `{ default }` of what
+ *   `require()` returns for a JSON module
+ */
+export declare function importModule(specifier: string): Promise<Record<string, unknown>>;

package/lib/import-module.js

@@ -0,0 +1,64 @@
+import { createRequire } from 'node:module';
+import { isModuleNotFoundError } from '@markuplint/shared';
+import { log } from './debug.js';
+import { fromFileURL } from './path-utils.js';
+const require = createRequire(import.meta.url);
+const iLog = log.extend('import-module');
+/**
+ * `import()` that takes a JSON module as one. Node.js and Deno load a JSON module through
+ * `import()` only with the import attribute `type: 'json'` (Bun takes it either way), and a
+ * module that a configuration names can be one, a configuration to `extends` or the data of
+ * `pretenders`, with or without the `.json` extension, as the `exports` map of a package can
+ * redirect a specifier. The attribute cannot be given up front, as a `.json` specifier can be
+ * redirected to a JavaScript module the same way, and the attribute would then be rejected; and
+ * Deno rejects a dynamic `import()` with the attribute as it rejects one without. So the
+ * specifier is imported as it is, and when the runtime reports a JSON module without the
+ * attribute ({@link isJsonWithoutAttribute}), or the `.json` extension says so, it is
+ * `require()`d instead: CommonJS takes a JSON module as it is on every runtime, a bare specifier
+ * and a path alike, and what it returns is handed over as the default export, the shape
+ * `import()` gives a JSON module. Any other failure of `import()` is thrown as it is, as that is
+ * what the callers read (a package that is not installed, a subpath that `exports` does not
+ * expose), and `require()` would only run the module's code again. The report is read before the
+ * code of a missing module, as Deno attaches that code to the report as well; the code decides
+ * only for a `.json` specifier that the runtime did not report as JSON.
+ *
+ * The `catch` is not guarded by `isFatalError()`: the runtimes report the missing attribute with
+ * a `TypeError`, which the guard would re-throw before the retry.
+ *
+ * @param specifier - What `import()` takes: a bare specifier, a `file:` URL, or an absolute path
+ *   as `moduleExists()` passes it (a Windows drive path fails here and is left to its
+ *   `require.resolve()`)
+ * @returns The module namespace that `import()` resolves to, or `{ default }` of what
+ *   `require()` returns for a JSON module
+ */
+export async function importModule(specifier) {
+    try {
+        return await import(specifier);
+    }
+    catch (error) {
+        const isJson = isJsonWithoutAttribute(error) || (specifier.endsWith('.json') && !isModuleNotFoundError(error));
+        if (!isJson) {
+            throw error;
+        }
+        iLog('`import()` refused %s as a JSON module (%O); taking `require()`', specifier, error);
+        return { default: require(specifier.startsWith('file:') ? fromFileURL(specifier) : specifier) };
+    }
+}
+/**
+ * Whether `import()` reported that the module is JSON and the attribute was not given. The
+ * wording is each runtime's own, observed in `general-import.runtime.spec.ts` in a fresh process
+ * of the runtime that runs the specs:
+ *
+ * - Node.js: the code `ERR_IMPORT_ATTRIBUTE_MISSING`
+ * - Deno: `Attempted to load JSON module without specifying "type": "json" attribute in the
+ *   import statement.`
+ * - Bun: never, as it takes a JSON module without the attribute
+ *
+ * @param error - What `import()` threw
+ * @returns `true` for that report
+ */
+function isJsonWithoutAttribute(error) {
+    return (error instanceof Error &&
+        (('code' in error && error.code === 'ERR_IMPORT_ATTRIBUTE_MISSING') ||
+            error.message.startsWith('Attempted to load JSON module without specifying "type": "json" attribute')));
+}

package/lib/module-exists.d.ts

@@ -1 +1,23 @@
+/**
+ * Whether `name` resolves to a module from where markuplint is installed: a package, or a file of
+ * one, as `extends`, `plugins`, `parser` and `specs` take a module.
+ *
+ * The resolution is that of this file's own location, as `import()` and `createRequire()` do it,
+ * never that of the configuration file that names the module, so a relative path is not a module
+ * here and is answered `false` without asking the runtime: resolved from this file, it would reach
+ * this package's own files or whatever lies above them. `resolveNameOrAbsPath` keeps a value
+ * spelled as a path away in the first place; `ConfigProvider` passes the names it is given as they
+ * are, so a relative one is answered `false` here and rejected as not absolute by its `#load`.
+ *
+ * The `catch` is not guarded by `isFatalError()`: what `import()` throws comes from the runtime's
+ * loader, which reports a file it cannot take as a module with a `SyntaxError` or a `TypeError`.
+ * Vite's module runner, which Vitest runs the specs in, reports such a file as a `Parse failure`,
+ * and that alone proves the file resolves; after any other failure the specifier is asked of
+ * `require.resolve()`, and what that throws, besides the module being absent or unexposed, is
+ * re-thrown as it is.
+ *
+ * @param name - A bare specifier, or an absolute path
+ * @returns `true` when the module resolves, including a file that the package's `exports` do not
+ *   expose, and a file that resolves but cannot be imported; `false` for a relative path
+ */
 export declare function moduleExists(name: string): Promise<boolean>;

package/lib/module-exists.js

@@ -1,21 +1,39 @@
 import { createRequire } from 'node:module';
 import { log } from './debug.js';
+import { importModule } from './import-module.js';
+import { isRelativePath } from './path-utils.js';
 const require = createRequire(import.meta.url);
 const mLog = log.extend('module-exists');
+/**
+ * Whether `name` resolves to a module from where markuplint is installed: a package, or a file of
+ * one, as `extends`, `plugins`, `parser` and `specs` take a module.
+ *
+ * The resolution is that of this file's own location, as `import()` and `createRequire()` do it,
+ * never that of the configuration file that names the module, so a relative path is not a module
+ * here and is answered `false` without asking the runtime: resolved from this file, it would reach
+ * this package's own files or whatever lies above them. `resolveNameOrAbsPath` keeps a value
+ * spelled as a path away in the first place; `ConfigProvider` passes the names it is given as they
+ * are, so a relative one is answered `false` here and rejected as not absolute by its `#load`.
+ *
+ * The `catch` is not guarded by `isFatalError()`: what `import()` throws comes from the runtime's
+ * loader, which reports a file it cannot take as a module with a `SyntaxError` or a `TypeError`.
+ * Vite's module runner, which Vitest runs the specs in, reports such a file as a `Parse failure`,
+ * and that alone proves the file resolves; after any other failure the specifier is asked of
+ * `require.resolve()`, and what that throws, besides the module being absent or unexposed, is
+ * re-thrown as it is.
+ *
+ * @param name - A bare specifier, or an absolute path
+ * @returns `true` when the module resolves, including a file that the package's `exports` do not
+ *   expose, and a file that resolves but cannot be imported; `false` for a relative path
+ */
 export async function moduleExists(name) {
+    if (isRelativePath(name)) {
+        return false;
+    }
     try {
-        await import(name);
+        await importModule(name);
     }
     catch (error) {
-        if (
-        // @ts-ignore
-        'code' in error &&
-            // @ts-ignore
-            error.code === 'ERR_IMPORT_ASSERTION_TYPE_MISSING') {
-            // It exists, but it is may be a JSON file.
-            mLog('Return true, but it caught Error in `import()`: %O', error);
-            return true;
-        }
         if (error instanceof Error && /^parse failure/i.test(error.message)) {
             // It exists, but it failed to parse.
             mLog('Return true, but it caught Error in `import()`: %O', error);

package/lib/path-to-abs-or-name.d.ts

@@ -1 +1,19 @@
+/**
+ * Applies {@link resolveNameOrAbsPath} to a property of a configuration in whichever shape it
+ * takes: one value, a list of values, or a map such as `parser` (an extension to a module or a
+ * file) and `overrides` (a glob to a configuration).
+ *
+ * In a map, or in an entry of a list, every string value is resolved unless `resolveProps` names
+ * the properties that hold a path, as `name` is the one of a `plugins` entry. The keys are left
+ * alone unless `resolveKey` says they are paths, as the globs of `overrides` are; the values of
+ * `overrides` are configurations in turn, which the caller resolves one by one.
+ *
+ * @template T - The shape of the property
+ * @param dir - The directory of the configuration file that declares the property
+ * @param filePath - The property, or `undefined` when the configuration does not hold it
+ * @param resolveProps - The properties of a map, or of an entry of a list, whose values are paths;
+ *   every string value is one when omitted
+ * @param resolveKey - Whether the keys of a map are paths
+ * @returns The property with its paths resolved, in the same shape, or `undefined` as given
+ */
 export declare function relPathToNameOrAbsPath<T extends string | readonly (string | Record<string, unknown>)[] | Readonly<Record<string, unknown>> | undefined>(dir: string, filePath?: T, resolveProps?: readonly string[], resolveKey?: boolean): Promise<T>;

package/lib/path-to-abs-or-name.js

@@ -1,4 +1,22 @@
 import { resolveNameOrAbsPath } from './resolve-name-or-abs-path.js';
+/**
+ * Applies {@link resolveNameOrAbsPath} to a property of a configuration in whichever shape it
+ * takes: one value, a list of values, or a map such as `parser` (an extension to a module or a
+ * file) and `overrides` (a glob to a configuration).
+ *
+ * In a map, or in an entry of a list, every string value is resolved unless `resolveProps` names
+ * the properties that hold a path, as `name` is the one of a `plugins` entry. The keys are left
+ * alone unless `resolveKey` says they are paths, as the globs of `overrides` are; the values of
+ * `overrides` are configurations in turn, which the caller resolves one by one.
+ *
+ * @template T - The shape of the property
+ * @param dir - The directory of the configuration file that declares the property
+ * @param filePath - The property, or `undefined` when the configuration does not hold it
+ * @param resolveProps - The properties of a map, or of an entry of a list, whose values are paths;
+ *   every string value is one when omitted
+ * @param resolveKey - Whether the keys of a map are paths
+ * @returns The property with its paths resolved, in the same shape, or `undefined` as given
+ */
 export async function relPathToNameOrAbsPath(dir, filePath, resolveProps, resolveKey = false) {
     if (filePath == null) {
         // @ts-ignore

package/lib/path-utils.d.ts

@@ -31,3 +31,12 @@ export declare function toFileURL(filePath: string): string;
 export declare function normalizeForIgnore(filePath: string, relative?: boolean): string;
 /** Glob libraries require forward slashes. */
 export declare function normalizeForGlob(filePath: string): string;
+/**
+ * Whether `filePath` is written as a relative path: a `.` or `..` segment first, followed by
+ * either separator (`./x`, `../x`, `.\x`, `..\x`) or by nothing (`.`, `..`). A dot-file name such
+ * as `.markuplintrc` is not one.
+ *
+ * @param filePath - A value of a configuration that names a file or a module
+ * @returns `true` for a relative path
+ */
+export declare function isRelativePath(filePath: string): boolean;

package/lib/path-utils.js

@@ -76,3 +76,14 @@ export function normalizeForIgnore(filePath, relative = false) {
 export function normalizeForGlob(filePath) {
     return toSlash(filePath);
 }
+/**
+ * Whether `filePath` is written as a relative path: a `.` or `..` segment first, followed by
+ * either separator (`./x`, `../x`, `.\x`, `..\x`) or by nothing (`.`, `..`). A dot-file name such
+ * as `.markuplintrc` is not one.
+ *
+ * @param filePath - A value of a configuration that names a file or a module
+ * @returns `true` for a relative path
+ */
+export function isRelativePath(filePath) {
+    return /^\.\.?(?:[/\\]|$)/.test(filePath);
+}

package/lib/resolve-name-or-abs-path.d.ts

@@ -1 +1,19 @@
+/**
+ * Resolves a value of a configuration that names a module or a file: a module name stays as it
+ * is, and a path becomes absolute against `dir`.
+ *
+ * A value spelled as a path (`./`, `../`, `.`, `..`, with either separator, or absolute) and a
+ * value with the `!` prefix of an exclusion are resolved without asking `moduleExists()`, which
+ * resolves a relative specifier from where markuplint is installed, not from the configuration: a
+ * file by that name there would make the value a module, keep it relative, and have it read from
+ * the working directory later. Installed in a project's `node_modules`, this package's `lib/` lies
+ * four directories below the project root (`node_modules/@markuplint/file-resolver/lib/`), so a
+ * configuration four directories below the root collided with the root's own `.markuplintrc`
+ * through `../../../../.markuplintrc`, and `../package.json` names this package's own. Any other
+ * value is tried as a module first, as the documentation of `extends` and its kin describes.
+ *
+ * @param dir - The directory of the configuration file that declares the value
+ * @param pathOrModName - The value, possibly with the `!` prefix of an exclusion
+ * @returns The module name as it is, or the absolute path, with the `!` prefix kept
+ */
 export declare function resolveNameOrAbsPath(dir: string, pathOrModName: string): Promise<string>;

package/lib/resolve-name-or-abs-path.js

@@ -2,13 +2,32 @@ import path from 'node:path';
 import { isPluginModuleName } from './is-plugin-module-name.js';
 import { isPresetModuleName } from './is-preset-module-name.js';
 import { moduleExists } from './module-exists.js';
+import { isRelativePath } from './path-utils.js';
+/**
+ * Resolves a value of a configuration that names a module or a file: a module name stays as it
+ * is, and a path becomes absolute against `dir`.
+ *
+ * A value spelled as a path (`./`, `../`, `.`, `..`, with either separator, or absolute) and a
+ * value with the `!` prefix of an exclusion are resolved without asking `moduleExists()`, which
+ * resolves a relative specifier from where markuplint is installed, not from the configuration: a
+ * file by that name there would make the value a module, keep it relative, and have it read from
+ * the working directory later. Installed in a project's `node_modules`, this package's `lib/` lies
+ * four directories below the project root (`node_modules/@markuplint/file-resolver/lib/`), so a
+ * configuration four directories below the root collided with the root's own `.markuplintrc`
+ * through `../../../../.markuplintrc`, and `../package.json` names this package's own. Any other
+ * value is tried as a module first, as the documentation of `extends` and its kin describes.
+ *
+ * @param dir - The directory of the configuration file that declares the value
+ * @param pathOrModName - The value, possibly with the `!` prefix of an exclusion
+ * @returns The module name as it is, or the absolute path, with the `!` prefix kept
+ */
 export async function resolveNameOrAbsPath(dir, pathOrModName) {
-    if ((await moduleExists(pathOrModName)) || isPresetModuleName(pathOrModName) || isPluginModuleName(pathOrModName)) {
-        return pathOrModName;
-    }
     const bangAndPath = /^(!)(.*)/.exec(pathOrModName) ?? [];
     const bang = bangAndPath[1] ?? '';
     const pathname = bangAndPath[2] ?? pathOrModName;
-    const absPath = path.resolve(dir, pathname);
-    return bang + absPath;
+    const isPath = bang !== '' || path.isAbsolute(pathname) || isRelativePath(pathname);
+    if (!isPath && (isPresetModuleName(pathname) || isPluginModuleName(pathname) || (await moduleExists(pathname)))) {
+        return pathOrModName;
+    }
+    return bang + path.resolve(dir, pathname);
 }

package/lib/resolve-pretenders.d.ts

@@ -60,6 +60,8 @@ export type PretenderResolver = {
      *   only on the call that read them.
      * @returns All resolved pretender definitions — a new array on every call,
      *   so the retained target-independent entries are never exposed to mutation
+     * @throws An `Error` that says how to install `@markuplint/pretenders` when `config.scan`
+     *   or `config.auto` needs it and it is not installed, with the error of the import as its `cause`
      */
     resolve(context?: ResolvePretendersContext, options?: ResolvePretendersOptions): Promise<Pretender[]>;
 };
@@ -70,7 +72,8 @@ export type PretenderResolver = {
  * kept as well — the host's next config resolution creates a new resolver).
  *
  * @param config - The pretenders configuration section from the optimized config
- * @returns The resolver; its `resolve()` yields `[]` when `config` is absent
+ * @returns The resolver; its `resolve()` yields `[]` when `config` is absent, and rejects as
+ *   {@link resolvePretenders} does when `@markuplint/pretenders` is needed and not installed
  */
 export declare function createPretenderResolver(config: PretendersConfig): PretenderResolver;
 /**
@@ -98,6 +101,10 @@ export declare function createPretenderResolver(config: PretendersConfig): Prete
  * @param context - The lint target's path/source, required only for `config.auto`
  * @param options - Where to report the files the result depends on
  * @returns An array of all resolved pretender definitions
+ * @throws An `Error` that says how to install `@markuplint/pretenders` when `config.scan` or
+ *   `config.auto` needs it and it is not installed (an optional peer of this package), with the
+ *   error of the import as its `cause`. A module that an installed `@markuplint/pretenders`
+ *   needs being missing is thrown as it is.
  */
 export declare function resolvePretenders(config: PretendersConfig, context?: ResolvePretendersContext, options?: ResolvePretendersOptions): Promise<Pretender[]>;
 /**
@@ -116,6 +123,8 @@ export declare function resolvePretenders(config: PretendersConfig, context?: Re
  * @param options - Where to report the files the result depends on
  * @returns The disambiguated pretender list, or `pretenders` itself (same
  *   reference) when there was nothing to resolve
+ * @throws An `Error` that says how to install `@markuplint/pretenders` when an entry has a
+ *   `filePath` and it is not installed, with the error of the import as its `cause`
  */
 export declare function disambiguatePretendersForFile(filePath: string, sourceCode: string, pretenders: readonly Pretender[], options?: ResolvePretendersOptions): Promise<readonly Pretender[]>;
 /**
@@ -136,7 +145,8 @@ export declare function hasResolvableCollision(pretenders: readonly Pretender[])
  * newly valid tsconfig `paths` alias keeps resolving as it did before the
  * change for the rest of the process's lifetime. A no-op (not an error) when
  * `@markuplint/pretenders` isn't installed, since nothing has populated its
- * caches in that case either.
+ * caches in that case either, and when it is installed but fails to load, which
+ * is logged under the `ml-fr` debug namespace: what needs it fails on its own, with the reason.
  *
  * @returns A promise that resolves once the caches have been cleared
  */

package/lib/resolve-pretenders.js

@@ -1,8 +1,38 @@
 import path from 'node:path';
 import { rebaseHandWrittenPretenderFilePath, rebasePretenderFilePath } from '@markuplint/ml-config';
+import { isFatalError, missingPackageOf } from '@markuplint/shared';
 import { glob } from 'glob';
+import { log } from './debug.js';
 import { generalImport } from './general-import.js';
 import { normalizeForGlob } from './path-utils.js';
+const PRETENDERS_PACKAGE = '@markuplint/pretenders';
+/**
+ * `@markuplint/pretenders` is an optional peer of this package (`peerDependenciesMeta`): installing markuplint
+ * does not install it, nor the parsers and the frameworks behind them, so it is loaded only for a
+ * configuration that needs it, and one that does is told how to install it rather than given the bare
+ * `ERR_MODULE_NOT_FOUND` of Node.
+ *
+ * Only the package itself missing gets that message. A module that an installed `@markuplint/pretenders`
+ * needs being missing is a fault of the installation, and is thrown as it is (see `missingPackageOf` in
+ * `@markuplint/shared`).
+ *
+ * @param name - The export to load
+ * @param needs - What needs it, as the start of the sentence of the error: an option of the configuration
+ * @returns The export
+ * @throws An `Error` that says how to install the package, with the error of the import as its `cause`
+ */
+async function importFromPretenders(name, needs) {
+    try {
+        const mod = await import('@markuplint/pretenders');
+        return mod[name];
+    }
+    catch (error) {
+        if (isFatalError(error) || missingPackageOf(error) !== PRETENDERS_PACKAGE) {
+            throw error;
+        }
+        throw new Error(`${needs} needs ${PRETENDERS_PACKAGE}, which is not installed. Add it to your project as a development dependency (for example, npm install --save-dev ${PRETENDERS_PACKAGE}), together with the parser package of each language you scan: @markuplint/vue-parser for .vue, @markuplint/svelte-parser for .svelte, @markuplint/astro-parser for .astro (and @markuplint/jsx-parser, @markuplint/mdx-parser for JSX and MDX).`, { cause: error });
+    }
+}
 /**
  * `Pretender.filePath` is written by scanners (and by hand, in `data`) relative to
  * their own base directory, which is meaningless once entries from
@@ -22,7 +52,8 @@ function rebasePretenderFilePaths(pretenders, baseDir) {
  * kept as well — the host's next config resolution creates a new resolver).
  *
  * @param config - The pretenders configuration section from the optimized config
- * @returns The resolver; its `resolve()` yields `[]` when `config` is absent
+ * @returns The resolver; its `resolve()` yields `[]` when `config` is absent, and rejects as
+ *   {@link resolvePretenders} does when `@markuplint/pretenders` is needed and not installed
  */
 export function createPretenderResolver(config) {
     // The promise is retained, not its result, so that overlapping first calls
@@ -71,6 +102,10 @@ export function createPretenderResolver(config) {
  * @param context - The lint target's path/source, required only for `config.auto`
  * @param options - Where to report the files the result depends on
  * @returns An array of all resolved pretender definitions
+ * @throws An `Error` that says how to install `@markuplint/pretenders` when `config.scan` or
+ *   `config.auto` needs it and it is not installed (an optional peer of this package), with the
+ *   error of the import as its `cause`. A module that an installed `@markuplint/pretenders`
+ *   needs being missing is thrown as it is.
  */
 export function resolvePretenders(config, context, options) {
     return createPretenderResolver(config).resolve(context, options);
@@ -118,7 +153,7 @@ async function resolveTargetIndependentPretenders(config) {
         data.push(...config.data.map(pretender => rebaseHandWrittenPretenderFilePath(pretender, p => path.resolve(cwd, p))));
     }
     if (config.scan) {
-        const { scan } = await import('@markuplint/pretenders');
+        const scan = await importFromPretenders('scan', 'The "pretenders.scan" option');
         for (const entry of config.scan) {
             const patterns = typeof entry.files === 'string' ? [entry.files] : [...entry.files];
             // The patterns are absolute paths of the platform (`#pathResolve`), which Windows writes
@@ -143,7 +178,7 @@ async function resolveTargetIndependentPretenders(config) {
  * `context`'s import graph to `data`, the target-independent entries.
  */
 async function appendAutoPretenders(data, context, auto, dependencies) {
-    const { autoScan } = await import('@markuplint/pretenders');
+    const autoScan = await importFromPretenders('autoScan', 'The "pretenders.auto" option');
     const scanned = await autoScan(context.filePath, context.sourceCode, {
         depth: auto === true ? undefined : auto.depth,
         dependencies,
@@ -189,12 +224,14 @@ async function appendAutoPretenders(data, context, auto, dependencies) {
  * @param options - Where to report the files the result depends on
  * @returns The disambiguated pretender list, or `pretenders` itself (same
  *   reference) when there was nothing to resolve
+ * @throws An `Error` that says how to install `@markuplint/pretenders` when an entry has a
+ *   `filePath` and it is not installed, with the error of the import as its `cause`
  */
 export async function disambiguatePretendersForFile(filePath, sourceCode, pretenders, options) {
     if (!pretenders.some(pretender => pretender.filePath)) {
         return pretenders;
     }
-    const { disambiguatePretenders } = await import('@markuplint/pretenders');
+    const disambiguatePretenders = await importFromPretenders('disambiguatePretenders', 'A pretender that has a `filePath`');
     // The same base the scanned pretenders' paths were made absolute from (see `rebasePretenderFilePaths`).
     return disambiguatePretenders(pretenders, {
         filePath,
@@ -233,11 +270,24 @@ export function hasResolvableCollision(pretenders) {
  * newly valid tsconfig `paths` alias keeps resolving as it did before the
  * change for the rest of the process's lifetime. A no-op (not an error) when
  * `@markuplint/pretenders` isn't installed, since nothing has populated its
- * caches in that case either.
+ * caches in that case either, and when it is installed but fails to load, which
+ * is logged under the `ml-fr` debug namespace: what needs it fails on its own, with the reason.
  *
  * @returns A promise that resolves once the caches have been cleared
  */
 export async function invalidatePretenderResolutionCaches() {
-    const pretendersMod = await import('@markuplint/pretenders').catch(() => null);
-    pretendersMod?.clearPretenderCaches();
+    let clearPretenderCaches;
+    try {
+        ({ clearPretenderCaches } = await import('@markuplint/pretenders'));
+    }
+    catch (error) {
+        // Clearing is best-effort, and what needs the package fails on its own with the reason when it is
+        // loaded, so a package that fails to load is logged and left to that. Tier-1-shaped errors are not
+        // told apart here either: a module the package needs runs as it loads, as in `generalImport`.
+        if (missingPackageOf(error) !== PRETENDERS_PACKAGE) {
+            log('Failed to load %s to clear its caches: %O', PRETENDERS_PACKAGE, error);
+        }
+        return;
+    }
+    clearPretenderCaches();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/file-resolver",
-	"version": "5.4.0",
+	"version": "5.5.0",
 	"description": "The file resolver of markuplint",
 	"repository": {
 		"type": "git",
@@ -31,25 +31,33 @@
 		"clean": "tsc --build --clean"
 	},
 	"devDependencies": {
+		"@markuplint/pretenders": "5.5.0",
 		"@types/node": "24.19.2"
 	},
+	"peerDependencies": {
+		"@markuplint/pretenders": "^5.4.0"
+	},
+	"peerDependenciesMeta": {
+		"@markuplint/pretenders": {
+			"optional": true
+		}
+	},
 	"dependencies": {
-		"@markuplint/html-parser": "5.4.0",
-		"@markuplint/ml-ast": "5.3.0",
-		"@markuplint/ml-config": "5.4.0",
-		"@markuplint/ml-core": "5.4.0",
-		"@markuplint/ml-spec": "5.4.0",
-		"@markuplint/parser-utils": "5.4.0",
-		"@markuplint/pretenders": "5.4.0",
-		"@markuplint/selector": "5.4.0",
-		"@markuplint/shared": "5.4.0",
+		"@markuplint/html-parser": "5.5.0",
+		"@markuplint/ml-ast": "5.5.0",
+		"@markuplint/ml-config": "5.5.0",
+		"@markuplint/ml-core": "5.5.0",
+		"@markuplint/ml-spec": "5.5.0",
+		"@markuplint/parser-utils": "5.5.0",
+		"@markuplint/selector": "5.5.0",
+		"@markuplint/shared": "5.5.0",
 		"cosmiconfig": "^10.0.1",
 		"debug": "^4.4.3",
-		"glob": "^13.0.6",
-		"ignore": "^7.0.12",
+		"glob": "^14.0.3",
+		"ignore": "^7.0.14",
 		"import-meta-resolve": "^4.2.0",
 		"jsonc": "^3.0.0",
-		"minimatch": "^10.2.6"
+		"minimatch": "^11.0.4"
 	},
-	"gitHead": "647f6fb5d5743f060678599c97e9c84b58970747"
+	"gitHead": "fedebcfd56eaec4642e68643b2f9e10750d810e1"
 }