@markuplint/file-resolver 5.3.0 → 5.4.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.4.0](https://github.com/markuplint/markuplint/compare/v5.3.0...v5.4.0) (2026-10-29)
+
+### Bug Fixes
+
+* **file-resolver:** do not run a throwing config file again through require() ([21b2e87](https://github.com/markuplint/markuplint/commit/21b2e87d836baa3e0747dee623845ddfc077c091)), closes [#4413](https://github.com/markuplint/markuplint/issues/4413)
+* **file-resolver:** find a Windows path written with forward slashes in the stack ([ea7336c](https://github.com/markuplint/markuplint/commit/ea7336c839365d67a3b0d6427d8d1c2b864769f1)), closes [#4413](https://github.com/markuplint/markuplint/issues/4413)
+* **file-resolver:** find the configuration above a nested package.json ([de7c887](https://github.com/markuplint/markuplint/commit/de7c887aebc5ce59bfdad08802ae23554abbda27)), closes [#4405](https://github.com/markuplint/markuplint/issues/4405)
+* **file-resolver:** report a config file that fails to load by its own path ([0fafeca](https://github.com/markuplint/markuplint/commit/0fafeca63d28164bcbbd7fecdaeefcb593a2ae7f)), closes [#4413](https://github.com/markuplint/markuplint/issues/4413)
+* **file-resolver:** resolve the paths of a configuration from the file that declares it ([b819519](https://github.com/markuplint/markuplint/commit/b819519236e3640b65965376ba2e78ea336e9593)), closes [#4406](https://github.com/markuplint/markuplint/issues/4406)
+* **file-resolver:** search the ancestors of a target whose directory does not exist ([75bdf1c](https://github.com/markuplint/markuplint/commit/75bdf1c7affce5eab88c091ca6a031c89ae29840)), closes [#4412](https://github.com/markuplint/markuplint/issues/4412)
+
+
 # [5.3.0](https://github.com/markuplint/markuplint/compare/v5.2.0...v5.3.0) (2026-10-21)
 
 ### Bug Fixes

package/lib/config-provider.d.ts

@@ -98,7 +98,12 @@ export declare class ConfigProvider {
      */
     resolve(targetFile: Readonly<MLFile>, names: readonly Nullable<string>[], cache?: boolean): Promise<ConfigSet>;
     /**
-     * Searches for a markuplint configuration file starting from the target file's directory.
+     * Searches for a markuplint configuration file starting from the target file's directory
+     * and going up through its ancestors; the nearest one wins. A `package.json` without a
+     * `markuplint` field is not a configuration file, so the search passes over it. A target
+     * directory that does not exist yet, such as that of an unsaved editor buffer in a new folder,
+     * does not end the search either: the search starts from that directory and goes on through
+     * its ancestors, the missing ones yielding nothing.
      *
      * @param targetFile - The file whose directory to search from
      * @returns The file path of the found config, or `null` if none was found

package/lib/config-provider.js

@@ -1,10 +1,10 @@
 import path from 'node:path';
-import { mergeConfig } from '@markuplint/ml-config';
+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 { clearAutoLoadRulesCache } from './auto-load-rules.js';
-import { load as loadConfig, search, clearExplorerCache } from './cosmiconfig.js';
+import { load as loadConfig, search, clearExplorerCache, configLoadErrorFiles } from './cosmiconfig.js';
 import { log } from './debug.js';
 import { generalImport } from './general-import.js';
 import { getPreset } from './get-preset.js';
@@ -136,7 +136,14 @@ export class ConfigProvider {
             return { stack, errs: [] };
         }
         if (config instanceof ConfigLoadError) {
-            stack.add(config.filePath);
+            // The files whose change can fix the error are recorded as well as `key`, as they can be
+            // ones that `key` imports through `$import`, or a target of it that does not exist yet.
+            // `key` is added last, so that it stays the file `#resolveBase` validates against, as when
+            // the load succeeds.
+            for (const filePath of configLoadErrorFiles(config)) {
+                stack.add(filePath);
+            }
+            stack.add(key);
             return {
                 stack,
                 errs: [config],
@@ -190,7 +197,7 @@ export class ConfigProvider {
             baseConfigSet = await this.#resolveBase(keys, cache, targetFile.path);
             this.#cache.set(key, baseConfigSet);
         }
-        return this.#applyOverrides(baseConfigSet, targetFile);
+        return await this.#applyOverrides(baseConfigSet, targetFile);
     }
     /**
      * The `names`-dependent, `targetFile`-independent part of {@link resolve}:
@@ -245,8 +252,13 @@ export class ConfigProvider {
      * replaces every earlier match, not just the base config. `appliedOverrides`
      * records that match order for `--show-config=details` to surface, since this
      * "last match wins outright" behavior is easy to mistake for a bug (see #4023).
+     *
+     * The plugins an override declares are loaded here, as `#resolveBase` cannot know which
+     * overrides apply. The result keeps every plugin of the base, replaced where the override
+     * declares the same one: a `reset` override that declares none still reaches the rules of
+     * the plugins the base loaded, as it did before the override's own were loaded at all.
      */
-    #applyOverrides(baseConfigSet, targetFile) {
+    async #applyOverrides(baseConfigSet, targetFile) {
         let config = baseConfigSet.config;
         const appliedOverrides = [];
         if (config.overrides) {
@@ -258,24 +270,53 @@ export class ConfigProvider {
                     appliedOverrides.push(glob);
                 }
             }
-            return config === baseConfigSet.config ? baseConfigSet : { ...baseConfigSet, config, appliedOverrides };
+            if (config === baseConfigSet.config) {
+                return baseConfigSet;
+            }
+            return {
+                ...(await this.#resolveOverridePlugins(baseConfigSet, config)),
+                config,
+                appliedOverrides,
+            };
         }
         return baseConfigSet;
     }
     /**
-     * Searches for a markuplint configuration file starting from the target file's directory.
+     * @param baseConfigSet - The base configuration set, which is never mutated
+     * @param config - The configuration after the overrides are applied
+     * @returns `baseConfigSet` with the plugins of `config` loaded in, or itself (same
+     * reference) when `config` declares none
+     */
+    async #resolveOverridePlugins(baseConfigSet, config) {
+        if (!config.plugins || config.plugins === baseConfigSet.config.plugins) {
+            return baseConfigSet;
+        }
+        const { plugins: declared, errors } = await resolvePlugins(config.plugins);
+        const baseNames = new Set(baseConfigSet.plugins.map(plugin => plugin.name));
+        const plugins = [
+            ...baseConfigSet.plugins.map(plugin => declared.find(d => d.name === plugin.name) ?? plugin),
+            ...declared.filter(plugin => !baseNames.has(plugin.name)),
+        ];
+        // `merge` mode declares the base's plugins again, and a plugin that is not found is cached
+        // as the error, so what the base already reported is not reported twice.
+        const reported = new Set(baseConfigSet.errs.map(error => error.message));
+        const errs = [...baseConfigSet.errs, ...errors.filter(error => !reported.has(error.message))];
+        return { ...baseConfigSet, plugins, errs };
+    }
+    /**
+     * Searches for a markuplint configuration file starting from the target file's directory
+     * and going up through its ancestors; the nearest one wins. A `package.json` without a
+     * `markuplint` field is not a configuration file, so the search passes over it. A target
+     * directory that does not exist yet, such as that of an unsaved editor buffer in a new folder,
+     * does not end the search either: the search starts from that directory and goes on through
+     * its ancestors, the missing ones yielding nothing.
      *
      * @param targetFile - The file whose directory to search from
      * @returns The file path of the found config, or `null` if none was found
      */
     async search(targetFile) {
-        const isExists = await targetFile.dirExists();
         if (cpLog.enabled) {
             cpLog('search: %s', targetFile.path);
-            cpLog('isExists: %s', isExists);
-        }
-        if (!isExists) {
-            return null;
         }
         const res = await search(targetFile.path, false);
         cpLog('searched config: %O', res);
@@ -381,26 +422,15 @@ export class ConfigProvider {
     async #pathResolve(config, filePath) {
         const optimizedConfig = mergeConfig(config);
         const dir = path.dirname(filePath);
+        // Only the keys of `overrides` (the globs) are resolved here; each value is a
+        // configuration of its own, whose paths are relative to the same directory.
+        const overrides = await relPathToNameOrAbsPath(dir, optimizedConfig.overrides, undefined, true);
         return {
-            ...optimizedConfig,
+            ...(await resolveConfigPaths(dir, optimizedConfig)),
             extends: await relPathToNameOrAbsPath(dir, optimizedConfig.extends),
-            plugins: await relPathToNameOrAbsPath(dir, optimizedConfig.plugins, ['name']),
-            parser: await relPathToNameOrAbsPath(dir, optimizedConfig.parser),
-            specs: await relPathToNameOrAbsPath(dir, optimizedConfig.specs),
-            excludeFiles: await relPathToNameOrAbsPath(dir, optimizedConfig.excludeFiles),
-            pretenders: optimizedConfig.pretenders
-                ? {
-                    ...optimizedConfig.pretenders,
-                    files: await relPathToNameOrAbsPath(dir, optimizedConfig.pretenders?.files),
-                    scan: optimizedConfig.pretenders?.scan?.map(entry => ({
-                        ...entry,
-                        files: typeof entry.files === 'string'
-                            ? path.resolve(dir, entry.files)
-                            : entry.files.map(f => path.resolve(dir, f)),
-                    })),
-                }
+            overrides: overrides
+                ? Object.fromEntries(await Promise.all(Object.entries(overrides).map(async ([glob, value]) => [glob, await resolveConfigPaths(dir, value)])))
                 : undefined,
-            overrides: await relPathToNameOrAbsPath(dir, optimizedConfig.overrides, undefined, true),
         };
     }
     #validateConfig(config, filePath) {
@@ -424,6 +454,55 @@ export class ConfigProvider {
         return errors;
     }
 }
+/**
+ * Resolves the paths a configuration holds against `dir`, the directory of the file that
+ * declares it. Once configurations from different directories are merged (`extends`), the
+ * directory a relative path belongs to is no longer known, so this runs for the top level and
+ * for the value of every `overrides` entry while it still is.
+ *
+ * Every property of a configuration that holds a path has to be resolved here: one missed is
+ * resolved at the top level but left relative inside `overrides` (or the reverse), and what is
+ * left relative is read from the working directory later.
+ *
+ * The result has no `undefined` property for what the configuration does not hold. An
+ * `overrides` value is the configuration itself under `reset` mode, so an `undefined` key
+ * would show up in it as a property it never had; under `merge` mode it would overwrite the
+ * value the base configuration holds. `mergeConfig` leaves none in an `overrides` value for
+ * the same reason.
+ *
+ * @template T - The configuration type: the top level, or the value of an `overrides` entry
+ * @param dir - The directory of the configuration file that declares `config`
+ * @param config - The configuration whose paths are resolved
+ * @returns The configuration with the paths resolved
+ */
+async function resolveConfigPaths(dir, config) {
+    return {
+        ...config,
+        ...(config.plugins && { plugins: await relPathToNameOrAbsPath(dir, config.plugins, ['name']) }),
+        ...(config.parser && { parser: await relPathToNameOrAbsPath(dir, config.parser) }),
+        ...(config.specs && { specs: await relPathToNameOrAbsPath(dir, config.specs) }),
+        ...(config.excludeFiles && { excludeFiles: await relPathToNameOrAbsPath(dir, config.excludeFiles) }),
+        ...(config.pretenders && {
+            pretenders: {
+                ...config.pretenders,
+                ...(config.pretenders.files && {
+                    files: await relPathToNameOrAbsPath(dir, config.pretenders.files),
+                }),
+                ...(config.pretenders.scan && {
+                    scan: config.pretenders.scan.map(entry => ({
+                        ...entry,
+                        files: typeof entry.files === 'string'
+                            ? path.resolve(dir, entry.files)
+                            : entry.files.map(f => path.resolve(dir, f)),
+                    })),
+                }),
+                ...(config.pretenders.data && {
+                    data: config.pretenders.data.map(pretender => rebaseHandWrittenPretenderFilePath(pretender, relPath => path.resolve(dir, relPath))),
+                }),
+            },
+        }),
+    };
+}
 async function load(filePath, cache, referrer) {
     if (!fileExists(filePath) && (await moduleExists(filePath))) {
         const config = (await generalImport(filePath)) ?? new ConfigLoadError('Module is not found', filePath, referrer);

package/lib/cosmiconfig.d.ts

@@ -10,6 +10,30 @@ type CosmiConfig = ReturnType<LoaderSync>;
  * content instead of the explorer's stale cache. See #4015.
  */
 export declare function clearExplorerCache(): void;
+/**
+ * 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 declare function search<T = CosmiConfig>(filePath: string, cacheClear: boolean): Promise<{
     filePath: string;
     config: T;
@@ -18,4 +42,29 @@ export declare function load<T = CosmiConfig>(filePath: string, cacheClear: bool
     filePath: string;
     config: T;
 }>;
+/**
+ * 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 declare function configLoadErrorFiles(error: ConfigLoadError): readonly string[];
+/**
+ * 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 declare function stackLocation(stack: string, filePaths: readonly string[]): string;
 export {};

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/index.d.ts

@@ -1,5 +1,6 @@
 export type { MLFile } from './ml-file/index.js';
 export * from './config-provider.js';
+export { configLoadErrorFiles } from './cosmiconfig.js';
 export * from './resolve-files.js';
 export * from './resolve-parser.js';
 export * from './resolve-pretenders.js';

package/lib/index.js

@@ -1,4 +1,5 @@
 export * from './config-provider.js';
+export { configLoadErrorFiles } from './cosmiconfig.js';
 export * from './resolve-files.js';
 export * from './resolve-parser.js';
 export * from './resolve-pretenders.js';

package/lib/ml-file/ml-file.d.ts

@@ -12,6 +12,10 @@ export declare class MLFile {
      */
     get nPath(): string;
     get path(): string;
+    /**
+     * Whether the file's directory exists. Only ENOENT counts as missing; any other `stat` failure
+     * throws. Kept as part of the public `MLFile` type, though nothing in this repository calls it.
+     */
     dirExists(): Promise<boolean>;
     getCode(): Promise<string>;
     ignored(globPath: string | readonly string[]): boolean;

package/lib/ml-file/ml-file.js

@@ -51,6 +51,10 @@ export class MLFile {
     get path() {
         return path.resolve(this.#dirname, this.#basename);
     }
+    /**
+     * Whether the file's directory exists. Only ENOENT counts as missing; any other `stat` failure
+     * throws. Kept as part of the public `MLFile` type, though nothing in this repository calls it.
+     */
     async dirExists() {
         return !!(await stat(this.#dirname));
     }

package/lib/resolve-pretenders.js

@@ -1,11 +1,13 @@
 import path from 'node:path';
-import { rebasePretenderFilePath } from '@markuplint/ml-config';
+import { rebaseHandWrittenPretenderFilePath, rebasePretenderFilePath } from '@markuplint/ml-config';
 import { glob } from 'glob';
 import { generalImport } from './general-import.js';
+import { normalizeForGlob } from './path-utils.js';
 /**
- * `Pretender.filePath` is written by scanners relative to their own base
- * directory, which is meaningless once entries from files/scan results
- * scattered across different directories are merged into one flat list.
+ * `Pretender.filePath` is written by scanners (and by hand, in `data`) relative to
+ * their own base directory, which is meaningless once entries from
+ * files/scan results/configurations scattered across different directories are
+ * merged into one flat list.
  * Rebasing to an absolute path immediately after each source is read is
  * what lets {@link disambiguatePretendersForFile} later compare a
  * pretender's origin file against the lint target's resolved imports.
@@ -108,13 +110,21 @@ async function resolveTargetIndependentPretenders(config) {
         }
     }
     if (config.data) {
-        data.push(...config.data);
+        // A configuration file's `data` is already absolute (resolved by the config provider
+        // from the file's own directory). What is relative here comes from a configuration with
+        // no file behind it (`MLEngine`'s `config` / `defaultConfig` option), which has no
+        // directory of its own, so it is read from `process.cwd()` — as its `scan` globs are.
+        const cwd = process.cwd();
+        data.push(...config.data.map(pretender => rebaseHandWrittenPretenderFilePath(pretender, p => path.resolve(cwd, p))));
     }
     if (config.scan) {
         const { scan } = await import('@markuplint/pretenders');
         for (const entry of config.scan) {
             const patterns = typeof entry.files === 'string' ? [entry.files] : [...entry.files];
-            const globResults = await Promise.all(patterns.map(p => glob(p)));
+            // The patterns are absolute paths of the platform (`#pathResolve`), which Windows writes
+            // with backslashes, and a glob reads one as an escape unless it is a slash. Only there:
+            // elsewhere a backslash is the escape a pattern may mean (`\[id\]`, a directory of brackets).
+            const globResults = await Promise.all(patterns.map(p => glob(process.platform === 'win32' ? normalizeForGlob(p) : p)));
             const resolved = globResults.flat().map(f => path.resolve(f));
             if (resolved.length > 0) {
                 const scanned = await scan(resolved, {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/file-resolver",
-	"version": "5.3.0",
+	"version": "5.4.0",
 	"description": "The file resolver of markuplint",
 	"repository": {
 		"type": "git",
@@ -34,15 +34,15 @@
 		"@types/node": "24.19.2"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "5.3.0",
+		"@markuplint/html-parser": "5.4.0",
 		"@markuplint/ml-ast": "5.3.0",
-		"@markuplint/ml-config": "5.3.0",
-		"@markuplint/ml-core": "5.3.0",
-		"@markuplint/ml-spec": "5.3.0",
-		"@markuplint/parser-utils": "5.3.0",
-		"@markuplint/pretenders": "5.3.0",
-		"@markuplint/selector": "5.3.0",
-		"@markuplint/shared": "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",
 		"cosmiconfig": "^10.0.1",
 		"debug": "^4.4.3",
 		"glob": "^13.0.6",
@@ -51,5 +51,5 @@
 		"jsonc": "^3.0.0",
 		"minimatch": "^10.2.6"
 	},
-	"gitHead": "f587cf0206c8426e57369a48d6d5fb22306eafde"
+	"gitHead": "647f6fb5d5743f060678599c97e9c84b58970747"
 }