@markuplint/file-resolver 5.3.0 → 5.5.0

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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
+
+* **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

@@ -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,13 +106,21 @@ 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
      */
     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 { nonNullableFilter, toNoEmptyStringArrayFromStringOrArray, ConfigLoadError, isFatalError, } 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';
@@ -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);
@@ -136,7 +144,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],
@@ -144,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);
@@ -178,19 +199,24 @@ 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) {
             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 +271,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 +289,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);
@@ -356,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);
@@ -381,26 +440,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) {
@@ -412,18 +460,71 @@ 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,
+                        }));
                     }
                 }
             }
         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 {};