@markuplint/file-resolver 5.0.0-rc.4 → 5.0.0-rc.6

package/CHANGELOG.md

@@ -3,6 +3,42 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.6](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.5...v5.0.0-rc.6) (2026-08-30)
+
+### Bug Fixes
+
+- resolveConfig(false) crashes with inline config (not a file path) ([#4018](https://github.com/markuplint/markuplint/issues/4018)) ([7e38b64](https://github.com/markuplint/markuplint/commit/7e38b64caa8cca69009ee765e4aada37fc48c559)), closes [#4015](https://github.com/markuplint/markuplint/issues/4015) [#4015](https://github.com/markuplint/markuplint/issues/4015)
+
+### Performance Improvements
+
+- share ConfigProvider across a run's files, fix latent overrides caching bug ([#4016](https://github.com/markuplint/markuplint/issues/4016)) ([fcc1875](https://github.com/markuplint/markuplint/commit/fcc1875b1a984a5ef1bb36aa04e7b3522fefc58e)), closes [#3997](https://github.com/markuplint/markuplint/issues/3997) [#3997](https://github.com/markuplint/markuplint/issues/3997)
+
+### BREAKING CHANGES
+
+- `ConfigProvider#resolve(targetFile, names, false)` no longer
+  clears the provider's store/cache/plugin-resolution caches by itself. Callers
+  that relied on `cache: false` alone to force a fresh re-read must now call
+  the new `ConfigProvider#invalidate()` first.
+
+# [5.0.0-rc.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Bug Fixes
+
+- **file-resolver:** make generalImport() OS-independent for POSIX absolute paths ([23aa492](https://github.com/markuplint/markuplint/commit/23aa492202a4b305022651210d9fc413e9baef2d)), closes [#3841](https://github.com/markuplint/markuplint/issues/3841) [#3843](https://github.com/markuplint/markuplint/issues/3843) [#3840](https://github.com/markuplint/markuplint/issues/3840)
+- **pretenders:** resolve same-named components via imports, not scan order ([#3957](https://github.com/markuplint/markuplint/issues/3957)) ([d46a514](https://github.com/markuplint/markuplint/commit/d46a5148c4d7afb156962f4ed795f40a9324e6c5)), closes [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951)
+
+### Code Refactoring
+
+- **rules:** redesign v5 rule system — naming, splits, specConformance ([#3989](https://github.com/markuplint/markuplint/issues/3989)) ([e925565](https://github.com/markuplint/markuplint/commit/e925565ce537848d7d1573369723cbce724a841b)), closes [#4](https://github.com/markuplint/markuplint/issues/4) [#aside-conditional-role-mapping-aria-13](https://github.com/markuplint/markuplint/issues/aside-conditional-role-mapping-aria-13)
+
+### Features
+
+- add `pretenders.auto` for on-demand import-graph resolution ([#3962](https://github.com/markuplint/markuplint/issues/3962)) ([5870671](https://github.com/markuplint/markuplint/commit/58706711a20c12cff080d49359f3f6443345eca3)), closes [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3959](https://github.com/markuplint/markuplint/issues/3959) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3959](https://github.com/markuplint/markuplint/issues/3959) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951)
+
+### BREAKING CHANGES
+
+- **rules:** with no alias coverage.
+
 # [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
 
 **Note:** Version bump only for package @markuplint/file-resolver

package/lib/config-provider.d.ts

@@ -7,9 +7,52 @@ import type { Nullable } from '@markuplint/shared';
  *
  * Handles `extends` chains, plugins, presets, overrides, and circular reference detection.
  * Configuration files are searched via cosmiconfig and cached by file path.
+ *
+ * Designed to be shared across every target file in a run (see
+ * `MLEngineOptions.configProvider` in `packages/markuplint/src/api/ml-engine.ts`):
+ * {@link resolve}'s cache is keyed by the resolved config's `names`, not by
+ * target file, so one instance reused across many files avoids redoing
+ * merge/validate/plugin-resolution once per file that shares the same
+ * config — see #3997.
  */
 export declare class ConfigProvider {
     #private;
+    /**
+     * Clears every cached and stored config entry: the base-config cache
+     * (`#cache`), the loaded/registered config store (`#store`), `set()`'s
+     * identity→key stabilization (`#autoKeys`), `resolve-plugins.ts`'s own
+     * module-level plugin-resolution cache, and the shared `cosmiconfig`
+     * explorer's own search/load caches (so {@link search}, called right
+     * after this, re-reads the current file content instead of a stale
+     * cosmiconfig-level cache).
+     *
+     * The `cosmiconfig` explorer and the `resolve-plugins.ts` cache are
+     * module-level singletons shared by every `ConfigProvider` instance in
+     * the process — clearing them here affects other instances too, not just
+     * this one. Harmless (they just re-search/re-load), but worth knowing
+     * when reasoning about a cache-busting re-resolve's blast radius.
+     *
+     * Callers doing a cache-busting re-resolve (e.g. watch mode after a file
+     * change) must call this **before** registering any inline config via
+     * {@link set}, and before {@link search}, for that same resolve —
+     * `resolve()` itself no longer clears anything, so a `set()`/`search()`
+     * call made after `invalidate()` survives through to `resolve()`. Wrap
+     * the whole `invalidate()` → `set()`/`search()` → `resolve()` sequence in
+     * {@link runExclusive} so an overlapping call on the same instance can't
+     * interleave its own `invalidate()` in the middle of it. See #4015.
+     */
+    invalidate(): void;
+    /**
+     * Runs `fn` exclusively with respect to every other `runExclusive` call on
+     * this instance: queued calls wait for earlier ones to settle before
+     * starting, so two overlapping cache-busting re-resolves (e.g. two
+     * watch-triggered `MLEngine#resolveConfig(false)` calls close together,
+     * whether from one engine's own provider or several engines sharing one)
+     * can't interleave — one call's {@link invalidate} can no longer wipe the
+     * `set()`/`search()` entries another call registered a moment earlier but
+     * hasn't yet consumed. See #4015.
+     */
+    runExclusive<T>(fn: () => Promise<T>): Promise<T>;
     /**
      * Recursively loads a configuration and all its `extends` dependencies.
      *
@@ -27,9 +70,27 @@ export declare class ConfigProvider {
      * Resolves the full configuration for a target file by merging all named configs,
      * resolving plugins, and applying file-specific overrides.
      *
+     * Split into a cacheable "base" phase (`#resolveBase`: merge/validate/plugin
+     * resolution/plugin-provided `extends`) and a per-call `overrides` phase, because
+     * `overrides` matching depends on `targetFile` while everything else in `names`
+     * resolution does not. Only the base result is cached (keyed on `names`, not on
+     * `targetFile`) — callers sharing one `ConfigProvider` across many target files
+     * (see #3997) get that work done once, while `overrides` are always re-evaluated
+     * per call so a `.vue`-only override never leaks into a `.html` file's result (or
+     * vice versa) just because they resolve the same `names`.
+     *
+     * Does NOT clear the provider's store/cache itself — call {@link invalidate}
+     * first if a fresh re-read is needed (e.g. a watch-triggered re-resolve).
+     * `cache` only controls whether an already-loaded `names` entry (this call's
+     * base-config cache, and — deeper still — cosmiconfig's own per-file cache in
+     * `#load`) is reused; it used to also wipe the store/cache up front, which
+     * discarded any `set()` call the caller had just made for this same resolve
+     * (e.g. `MLEngine#resolveConfig()` registering inline `config`/`defaultConfig`
+     * right before calling this) — see #4015.
+     *
      * @param targetFile - The file being linted
      * @param names - Config file paths or module names to merge
-     * @param cache - Whether to use cached results
+     * @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>;
@@ -45,7 +106,22 @@ export declare class ConfigProvider {
      *
      * @param config - The optimized configuration to store
      * @param key - An optional key to store the config under; auto-generated if omitted
+     * @param identity - Object identity to auto-key on when `key` is omitted (e.g. the
+     * caller's original, pre-merge config object). Repeated calls with the same
+     * `identity` reuse the same generated key instead of minting a fresh UUID each
+     * time, so `resolve()`'s base cache can hit for inline (non-file-path) config
+     * shared across multiple target files — see #3997. Falls back to `config` itself
+     * (which is rebuilt fresh by every caller today, so this is a no-op unless a
+     * caller passes a stable `identity`).
+     *
+     * **Invariant**: an `identity` must correspond to `config` content that is
+     * effectively immutable for as long as that identity is reused — a second
+     * call with the same `identity` but *different* `config` content returns
+     * the *first* call's key/content, silently discarding the new content. Not
+     * reachable via `MLEngine`'s call sites today (they hold `options.config`/
+     * `defaultConfig` as one unchanged reference per run); a future caller
+     * passing a reused identity for genuinely different content would hit this.
      * @returns The key under which the config was stored
      */
-    set(config: OptimizedConfig, key?: string): string;
+    set(config: OptimizedConfig, key?: string, identity?: object): string;
 }

package/lib/config-provider.js

@@ -3,7 +3,7 @@ import { mergeConfig } from '@markuplint/ml-config';
 import { ConfigParserError } from '@markuplint/parser-utils';
 import { InvalidSelectorError, createSelector } from '@markuplint/selector';
 import { nonNullableFilter, toNoEmptyStringArrayFromStringOrArray, ConfigLoadError } from '@markuplint/shared';
-import { load as loadConfig, search } from './cosmiconfig.js';
+import { load as loadConfig, search, clearExplorerCache } from './cosmiconfig.js';
 import { log } from './debug.js';
 import { generalImport } from './general-import.js';
 import { getPreset } from './get-preset.js';
@@ -20,12 +20,89 @@ const KEY_SEPARATOR = '__ML_CONFIG_MERGE__';
  *
  * Handles `extends` chains, plugins, presets, overrides, and circular reference detection.
  * Configuration files are searched via cosmiconfig and cached by file path.
+ *
+ * Designed to be shared across every target file in a run (see
+ * `MLEngineOptions.configProvider` in `packages/markuplint/src/api/ml-engine.ts`):
+ * {@link resolve}'s cache is keyed by the resolved config's `names`, not by
+ * target file, so one instance reused across many files avoids redoing
+ * merge/validate/plugin-resolution once per file that shares the same
+ * config — see #3997.
  */
 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
+     * across repeated calls with the *same* object reference (e.g. one caller
+     * sharing one `ConfigProvider` — and one `options.config`/`defaultConfig`
+     * object — across many target files). Without this, `set()` would mint a
+     * fresh UUID per call even for identical content, so `resolve()`'s cache
+     * (keyed on that UUID) would never hit for inline (non-file-path) config.
+     * Keyed on object identity, not content, so it costs nothing to check and
+     * needs no hashing of arbitrary config shapes.
+     */
+    #autoKeys = new WeakMap();
+    /**
+     * Serializes {@link runExclusive} calls on this instance.
+     */
+    #queue = Promise.resolve();
+    /**
+     * Clears every cached and stored config entry: the base-config cache
+     * (`#cache`), the loaded/registered config store (`#store`), `set()`'s
+     * identity→key stabilization (`#autoKeys`), `resolve-plugins.ts`'s own
+     * module-level plugin-resolution cache, and the shared `cosmiconfig`
+     * explorer's own search/load caches (so {@link search}, called right
+     * after this, re-reads the current file content instead of a stale
+     * cosmiconfig-level cache).
+     *
+     * The `cosmiconfig` explorer and the `resolve-plugins.ts` cache are
+     * module-level singletons shared by every `ConfigProvider` instance in
+     * the process — clearing them here affects other instances too, not just
+     * this one. Harmless (they just re-search/re-load), but worth knowing
+     * when reasoning about a cache-busting re-resolve's blast radius.
+     *
+     * Callers doing a cache-busting re-resolve (e.g. watch mode after a file
+     * change) must call this **before** registering any inline config via
+     * {@link set}, and before {@link search}, for that same resolve —
+     * `resolve()` itself no longer clears anything, so a `set()`/`search()`
+     * call made after `invalidate()` survives through to `resolve()`. Wrap
+     * the whole `invalidate()` → `set()`/`search()` → `resolve()` sequence in
+     * {@link runExclusive} so an overlapping call on the same instance can't
+     * interleave its own `invalidate()` in the middle of it. See #4015.
+     */
+    invalidate() {
+        this.#store.clear();
+        this.#cache.clear();
+        this.#autoKeys = new WeakMap();
+        cacheClear();
+        clearExplorerCache();
+    }
+    /**
+     * Runs `fn` exclusively with respect to every other `runExclusive` call on
+     * this instance: queued calls wait for earlier ones to settle before
+     * starting, so two overlapping cache-busting re-resolves (e.g. two
+     * watch-triggered `MLEngine#resolveConfig(false)` calls close together,
+     * whether from one engine's own provider or several engines sharing one)
+     * can't interleave — one call's {@link invalidate} can no longer wipe the
+     * `set()`/`search()` entries another call registered a moment earlier but
+     * hasn't yet consumed. See #4015.
+     */
+    async runExclusive(fn) {
+        const previous = this.#queue;
+        let release;
+        this.#queue = new Promise(resolve => {
+            release = resolve;
+        });
+        await previous;
+        try {
+            return await fn();
+        }
+        finally {
+            release();
+        }
+    }
     /**
      * Recursively loads a configuration and all its `extends` dependencies.
      *
@@ -77,28 +154,50 @@ export class ConfigProvider {
      * Resolves the full configuration for a target file by merging all named configs,
      * resolving plugins, and applying file-specific overrides.
      *
+     * Split into a cacheable "base" phase (`#resolveBase`: merge/validate/plugin
+     * resolution/plugin-provided `extends`) and a per-call `overrides` phase, because
+     * `overrides` matching depends on `targetFile` while everything else in `names`
+     * resolution does not. Only the base result is cached (keyed on `names`, not on
+     * `targetFile`) — callers sharing one `ConfigProvider` across many target files
+     * (see #3997) get that work done once, while `overrides` are always re-evaluated
+     * per call so a `.vue`-only override never leaks into a `.html` file's result (or
+     * vice versa) just because they resolve the same `names`.
+     *
+     * Does NOT clear the provider's store/cache itself — call {@link invalidate}
+     * first if a fresh re-read is needed (e.g. a watch-triggered re-resolve).
+     * `cache` only controls whether an already-loaded `names` entry (this call's
+     * base-config cache, and — deeper still — cosmiconfig's own per-file cache in
+     * `#load`) is reused; it used to also wipe the store/cache up front, which
+     * discarded any `set()` call the caller had just made for this same resolve
+     * (e.g. `MLEngine#resolveConfig()` registering inline `config`/`defaultConfig`
+     * right before calling this) — see #4015.
+     *
      * @param targetFile - The file being linted
      * @param names - Config file paths or module names to merge
-     * @param cache - Whether to use cached results
+     * @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) {
-        if (!cache) {
-            this.#store.clear();
-            this.#cache.clear();
-            cacheClear();
-        }
         const keys = names.filter(nonNullableFilter);
         const key = keys.join(KEY_SEPARATOR);
-        const currentConfig = this.#cache.get(key);
-        if (currentConfig) {
-            return currentConfig;
+        let baseConfigSet = this.#cache.get(key);
+        if (!baseConfigSet) {
+            baseConfigSet = await this.#resolveBase(keys, cache, targetFile.path);
+            this.#cache.set(key, baseConfigSet);
         }
-        let configSet = await this.#mergeConfigs(keys, cache, targetFile.path);
+        return this.#applyOverrides(baseConfigSet, targetFile);
+    }
+    /**
+     * The `names`-dependent, `targetFile`-independent part of {@link resolve}:
+     * merges all named configs, validates, resolves plugins, and expands
+     * plugin-provided `extends`. Safe to cache under a `names`-only key.
+     */
+    async #resolveBase(keys, cache, referrer) {
+        let configSet = await this.#mergeConfigs(keys, cache, referrer);
         const filePath = [...configSet.files].toReversed()[0];
         if (!filePath) {
             throw new ConfigParserError('Config file not found', {
-                filePath: targetFile.path,
+                filePath: referrer,
             });
         }
         const errors = this.#validateConfig(configSet.config, filePath);
@@ -120,36 +219,33 @@ export class ConfigProvider {
                     }
                 }
             }
-            configSet = await this.#mergeConfigs([...keys, ...extendHelds], cache, targetFile.path);
+            configSet = await this.#mergeConfigs([...keys, ...extendHelds], cache, referrer);
             this.#held.clear();
         }
-        // Resolves `overrides`
-        if (configSet.config.overrides) {
-            const overrides = configSet.config.overrides;
-            const globs = Object.keys(overrides);
-            for (const glob of globs) {
-                const isMatched = targetFile.matches(glob);
-                const config = overrides[glob];
-                if (isMatched && config) {
-                    switch (configSet.config.overrideMode) {
-                        case 'merge': {
-                            configSet.config = mergeConfig(configSet.config, config);
-                            break;
-                        }
-                        default: /* or "reset" */ {
-                            configSet.config = config;
-                            break;
-                        }
-                    }
-                }
-            }
-        }
-        const result = {
+        return {
             ...configSet,
             plugins,
         };
-        this.#cache.set(key, result);
-        return result;
+    }
+    /**
+     * The `targetFile`-dependent part of {@link resolve}: matches `config.overrides`
+     * globs against `targetFile` and applies whichever match, per `overrideMode`.
+     * Never mutates `baseConfigSet` — returns it unchanged (same reference) when no
+     * override matches, or a shallow copy with a freshly computed `config` otherwise,
+     * so the cached base entry stays valid for the next target file.
+     */
+    #applyOverrides(baseConfigSet, targetFile) {
+        let config = baseConfigSet.config;
+        if (config.overrides) {
+            const overrides = config.overrides;
+            for (const glob of Object.keys(overrides)) {
+                const overrideConfig = overrides[glob];
+                if (targetFile.matches(glob) && overrideConfig) {
+                    config = config.overrideMode === 'merge' ? mergeConfig(config, overrideConfig) : overrideConfig;
+                }
+            }
+        }
+        return config === baseConfigSet.config ? baseConfigSet : { ...baseConfigSet, config };
     }
     /**
      * Searches for a markuplint configuration file starting from the target file's directory.
@@ -180,12 +276,37 @@ export class ConfigProvider {
      *
      * @param config - The optimized configuration to store
      * @param key - An optional key to store the config under; auto-generated if omitted
+     * @param identity - Object identity to auto-key on when `key` is omitted (e.g. the
+     * caller's original, pre-merge config object). Repeated calls with the same
+     * `identity` reuse the same generated key instead of minting a fresh UUID each
+     * time, so `resolve()`'s base cache can hit for inline (non-file-path) config
+     * shared across multiple target files — see #3997. Falls back to `config` itself
+     * (which is rebuilt fresh by every caller today, so this is a no-op unless a
+     * caller passes a stable `identity`).
+     *
+     * **Invariant**: an `identity` must correspond to `config` content that is
+     * effectively immutable for as long as that identity is reused — a second
+     * call with the same `identity` but *different* `config` content returns
+     * the *first* call's key/content, silently discarding the new content. Not
+     * reachable via `MLEngine`'s call sites today (they hold `options.config`/
+     * `defaultConfig` as one unchanged reference per run); a future caller
+     * passing a reused identity for genuinely different content would hit this.
      * @returns The key under which the config was stored
      */
-    set(config, key) {
-        key = key ?? uuid();
-        this.#store.set(key, config);
-        return key;
+    set(config, key, identity) {
+        if (key != null) {
+            this.#store.set(key, config);
+            return key;
+        }
+        const identityKey = identity ?? config;
+        const existingKey = this.#autoKeys.get(identityKey);
+        if (existingKey != null) {
+            return existingKey;
+        }
+        const newKey = uuid();
+        this.#store.set(newKey, config);
+        this.#autoKeys.set(identityKey, newKey);
+        return newKey;
     }
     async #load(filePath, cache, referrer) {
         const entity = this.#store.get(filePath);

package/lib/cosmiconfig.d.ts

@@ -1,6 +1,15 @@
 import type { LoaderSync } from 'cosmiconfig';
 import { ConfigLoadError } from '@markuplint/shared';
 type CosmiConfig = ReturnType<LoaderSync>;
+/**
+ * Clears the shared `cosmiconfig` explorer's own internal search/load caches.
+ * Distinct from this module's `cacheClear` parameters (which clear the same
+ * caches but only as a side effect of one `search`/`load` call) — this lets a
+ * caller (see `ConfigProvider#invalidate`) clear them up front, before any
+ * `search`/`load` call, so a subsequent `search` reads the current file
+ * content instead of the explorer's stale cache. See #4015.
+ */
+export declare function clearExplorerCache(): void;
 export declare function search<T = CosmiConfig>(filePath: string, cacheClear: boolean): Promise<{
     filePath: string;
     config: T;

package/lib/cosmiconfig.js

@@ -40,6 +40,17 @@ const explorer = cosmiconfig('markuplint', {
     },
     searchStrategy: 'project',
 });
+/**
+ * Clears the shared `cosmiconfig` explorer's own internal search/load caches.
+ * Distinct from this module's `cacheClear` parameters (which clear the same
+ * caches but only as a side effect of one `search`/`load` call) — this lets a
+ * caller (see `ConfigProvider#invalidate`) clear them up front, before any
+ * `search`/`load` call, so a subsequent `search` reads the current file
+ * content instead of the explorer's stale cache. See #4015.
+ */
+export function clearExplorerCache() {
+    explorer.clearCaches();
+}
 export async function search(filePath, cacheClear) {
     if (cacheClear) {
         explorer.clearCaches();

package/lib/general-import.js

@@ -1,11 +1,10 @@
 import fs from 'node:fs/promises';
 import { createRequire } from 'node:module';
 import path from 'node:path';
-import { pathToFileURL } from 'node:url';
 import { isFatalError } from '@markuplint/shared';
 import { resolve } from 'import-meta-resolve';
 import { log } from './debug.js';
-import { fromFileURL } from './path-utils.js';
+import { fromFileURL, toFileURL } from './path-utils.js';
 const gLog = log.extend('general-import');
 const gLogSuccess = gLog.extend('success');
 const gLogError = gLog.extend('error');
@@ -27,11 +26,11 @@ export async function generalImport(name) {
         return result;
     }
     try {
-        // Convert absolute paths to file:// URL format
-        let importPath = name;
-        if (path.isAbsolute(name)) {
-            // Use Node.js pathToFileURL function to convert to a proper URL
-            importPath = pathToFileURL(name).href;
+        // Convert absolute paths to file:// URL format. `toFileURL()` is
+        // OS-independent (see #3840 — Node's `pathToFileURL()` resolves a
+        // POSIX-style absolute path against the current Windows drive).
+        const importPath = toFileURL(name);
+        if (importPath !== name) {
             gLog('Converted to file URL: %s', importPath);
         }
         const imported = await import(importPath);
@@ -41,6 +40,18 @@ export async function generalImport(name) {
         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 &&
@@ -93,13 +104,10 @@ export async function generalImport(name) {
     }
 }
 /**
- * Detects a bare package subpath specifier (e.g., `@scope/pkg/file.json`)
- * and resolves it to an absolute file path when the package's exports map
- * does not include the subpath.
- *
- * Returns the absolute path if resolution succeeds, or `null` if:
+ * Returns `null` (rather than throwing) in three distinct cases that callers
+ * treat identically — no bypass is needed:
  * - The specifier is not a package subpath (absolute path, relative path, no subpath)
- * - The package's exports map already includes the subpath (no bypass needed)
+ * - The package's exports map already includes the subpath
  * - The package cannot be found at all
  */
 function resolvePackageSubpath(name) {
@@ -138,9 +146,6 @@ function resolvePackageSubpath(name) {
         return null;
     }
 }
-/**
- * Resolves the root directory of a package by name.
- */
 function resolvePackageDir(packageName) {
     // Try CJS require.resolve first — it can often resolve package.json
     // even when the ESM exports map doesn't include it

package/lib/path-utils.d.ts

@@ -1,19 +1,33 @@
-/**
- * Convert OS-native separators to forward slashes.
- * Identity function on POSIX.
- */
+/** Identity function on POSIX. */
 export declare function toSlash(filePath: string): string;
-/**
- * Convert a `file://` URL to a native file path using Node.js built-in.
- * Correctly handles URL encoding, UNC paths, and all drive letters.
- */
 export declare function fromFileURL(fileUrl: string): string;
 /**
- * Normalize a path for the `ignore` library (gitignore-style matching).
- * Removes drive letters, converts to forward slashes, and optionally makes relative.
+ * Convert an absolute file path (Windows or POSIX) into a `file://` URL
+ * suitable for `import()`. Bare module specifiers and relative paths are
+ * returned unchanged.
+ *
+ * Node's `pathToFileURL()` is intentionally avoided: on Windows it
+ * resolves a POSIX-style absolute path against the *current drive* and
+ * emits `file:///D:/tmp/foo` instead of `file:///tmp/foo` (#3840); on
+ * POSIX it likewise mishandles Windows-style drive paths. Constructing
+ * the URL ourselves keeps the function OS-independent so POSIX CI
+ * exercises the Windows code path. Each segment is percent-encoded so
+ * that spaces (`Program Files`), non-ASCII characters (e.g. Japanese
+ * usernames), and URL-reserved characters like `#` / `?` do not get
+ * reinterpreted as fragment / query delimiters by Node's URL parser.
+ *
+ * Mirrors `vscode/src/server/get-module.ts`'s `toImportSpecifier()` —
+ * keep the two in sync when adjusting Windows-path handling.
+ *
+ * Known limitation: UNC paths (`\\server\share\...`) are passed through
+ * unchanged.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/3840
+ * @see https://github.com/markuplint/markuplint/issues/3836
+ * @see https://nodejs.org/api/esm.html#urls
  */
+export declare function toFileURL(filePath: string): string;
+/** Normalizes for the `ignore` library, whose matching is gitignore-style. */
 export declare function normalizeForIgnore(filePath: string, relative?: boolean): string;
-/**
- * Normalize a path for glob libraries (forward slashes required).
- */
+/** Glob libraries require forward slashes. */
 export declare function normalizeForGlob(filePath: string): string;

package/lib/path-utils.js

@@ -1,23 +1,57 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
-/**
- * Convert OS-native separators to forward slashes.
- * Identity function on POSIX.
- */
+/** Identity function on POSIX. */
 export function toSlash(filePath) {
     return filePath.replaceAll('\\', '/');
 }
-/**
- * Convert a `file://` URL to a native file path using Node.js built-in.
- * Correctly handles URL encoding, UNC paths, and all drive letters.
- */
 export function fromFileURL(fileUrl) {
     return fileURLToPath(fileUrl);
 }
 /**
- * Normalize a path for the `ignore` library (gitignore-style matching).
- * Removes drive letters, converts to forward slashes, and optionally makes relative.
+ * Convert an absolute file path (Windows or POSIX) into a `file://` URL
+ * suitable for `import()`. Bare module specifiers and relative paths are
+ * returned unchanged.
+ *
+ * Node's `pathToFileURL()` is intentionally avoided: on Windows it
+ * resolves a POSIX-style absolute path against the *current drive* and
+ * emits `file:///D:/tmp/foo` instead of `file:///tmp/foo` (#3840); on
+ * POSIX it likewise mishandles Windows-style drive paths. Constructing
+ * the URL ourselves keeps the function OS-independent so POSIX CI
+ * exercises the Windows code path. Each segment is percent-encoded so
+ * that spaces (`Program Files`), non-ASCII characters (e.g. Japanese
+ * usernames), and URL-reserved characters like `#` / `?` do not get
+ * reinterpreted as fragment / query delimiters by Node's URL parser.
+ *
+ * Mirrors `vscode/src/server/get-module.ts`'s `toImportSpecifier()` —
+ * keep the two in sync when adjusting Windows-path handling.
+ *
+ * Known limitation: UNC paths (`\\server\share\...`) are passed through
+ * unchanged.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/3840
+ * @see https://github.com/markuplint/markuplint/issues/3836
+ * @see https://nodejs.org/api/esm.html#urls
  */
+export function toFileURL(filePath) {
+    const isWindowsAbsolute = /^[a-z]:[/\\]/i.test(filePath);
+    const isPosixAbsolute = filePath.startsWith('/');
+    if (!isWindowsAbsolute && !isPosixAbsolute) {
+        return filePath;
+    }
+    if (isWindowsAbsolute) {
+        // The drive-letter segment (`c:`) is kept as-is to match the
+        // `pathToFileURL` output shape on Windows (`file:///c:/...`).
+        const [drive, ...rest] = filePath.replaceAll('\\', '/').split('/');
+        const encoded = [drive, ...rest.map(segment => encodeURIComponent(segment))].join('/');
+        return `file:///${encoded}`;
+    }
+    // POSIX absolute path. Splitting `/tmp/foo` by `/` yields `['', 'tmp',
+    // 'foo']`; the leading empty element produces the `file:///` prefix
+    // after `join('/')`, so the round-trip is exactly `file:///tmp/foo`.
+    const segments = filePath.split('/').map(segment => encodeURIComponent(segment));
+    return `file://${segments.join('/')}`;
+}
+/** Normalizes for the `ignore` library, whose matching is gitignore-style. */
 export function normalizeForIgnore(filePath, relative = false) {
     const hasBang = filePath.startsWith('!');
     if (hasBang) {
@@ -38,9 +72,7 @@ export function normalizeForIgnore(filePath, relative = false) {
     }
     return filePath;
 }
-/**
- * Normalize a path for glob libraries (forward slashes required).
- */
+/** Glob libraries require forward slashes. */
 export function normalizeForGlob(filePath) {
     return toSlash(filePath);
 }

package/lib/resolve-pretenders.d.ts

@@ -1,8 +1,20 @@
 import type { OptimizedConfig, Pretender } from '@markuplint/ml-config';
 type PretendersConfig = OptimizedConfig['pretenders'];
+/**
+ * The lint target's own identity, needed only to resolve `config.auto`.
+ * Omitting this (or omitting `config.auto`) skips auto-resolution entirely,
+ * so every other resolution source works exactly as before without it.
+ */
+export type ResolvePretendersContext = {
+    /** Absolute path of the file being linted */
+    readonly filePath: string;
+    /** Full source text of the file being linted (may be unsaved editor content) */
+    readonly sourceCode: string;
+};
 /**
  * Resolves pretender definitions from files, imported modules, inline data,
- * and dynamic component scanning in the configuration.
+ * dynamic component scanning, and (when `context` is given) the lint
+ * target's own import graph.
  *
  * Resolution order:
  * 1. `config.files` — direct import of pretender data files
@@ -12,9 +24,53 @@ type PretendersConfig = OptimizedConfig['pretenders'];
  * 3. `config.data` — inline pretender definitions
  * 4. `config.scan` — dynamic component scanning via glob patterns
  *    (`files` accepts `string | string[]`)
+ * 5. `config.auto` — on-demand scan of `context`'s own import graph (requires
+ *    `context`; a no-op without it, e.g. when the caller has no lint target yet)
  *
  * @param config - The pretenders configuration section from the optimized config
+ * @param context - The lint target's path/source, required only for `config.auto`
  * @returns An array of all resolved pretender definitions
  */
-export declare function resolvePretenders(config: PretendersConfig): Promise<Pretender[]>;
+export declare function resolvePretenders(config: PretendersConfig, context?: ResolvePretendersContext): Promise<Pretender[]>;
+/**
+ * Resolves selector collisions in `pretenders` for the specific file about
+ * to be linted, deferring to `@markuplint/pretenders`' `disambiguatePretenders`
+ * only when there's actually a same-selector, file-backed collision to
+ * resolve — this keeps the common case (no ambiguity) free of both the
+ * dynamic import and any file/AST work.
+ *
+ * @param filePath - Absolute path of the file being linted
+ * @param sourceCode - Full source text of the file being linted
+ * @param pretenders - The flat pretender list {@link resolvePretenders} produced
+ * @returns The disambiguated pretender list, or `pretenders` itself (same
+ *   reference) when there was no collision to resolve
+ */
+export declare function disambiguatePretendersForFile(filePath: string, sourceCode: string, pretenders: readonly Pretender[]): Promise<readonly Pretender[]>;
+/**
+ * Deliberately gates on selector+filePath duplication alone — NOT on the
+ * selector name shape `@markuplint/pretenders`' `disambiguatePretenders`
+ * actually resolves (plain identifiers only). Duplicating that name-shape
+ * check here would let the two independently maintained filters drift out
+ * of sync: if the real filter is ever loosened without updating this one,
+ * this fast-path gate would keep skipping the dynamic import for cases the
+ * real logic would now handle, silently disabling disambiguation for them.
+ * Being a strict superset costs at most an unnecessary dynamic import for
+ * selectors the real logic ends up not touching — never a missed one.
+ *
+ * @param pretenders - The flat pretender list to check
+ * @returns `true` if some `selector` is shared by two or more `filePath`-backed entries
+ */
+export declare function hasResolvableCollision(pretenders: readonly Pretender[]): boolean;
+/**
+ * Clears `@markuplint/pretenders`' module-level import/export resolution
+ * caches. Call this whenever a lint host re-resolves config without cache
+ * (e.g. watch mode after a file change) — otherwise a renamed export or a
+ * 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.
+ *
+ * @returns A promise that resolves once the caches have been cleared
+ */
+export declare function invalidatePretenderResolutionCaches(): Promise<void>;
 export {};

package/lib/resolve-pretenders.js

@@ -1,9 +1,22 @@
 import path from 'node:path';
+import { rebasePretenderFilePath } from '@markuplint/ml-config';
 import { glob } from 'glob';
 import { generalImport } from './general-import.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.
+ * 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.
+ */
+function rebasePretenderFilePaths(pretenders, baseDir) {
+    return pretenders.map(pretender => rebasePretenderFilePath(pretender, relPath => path.resolve(baseDir, relPath)));
+}
 /**
  * Resolves pretender definitions from files, imported modules, inline data,
- * and dynamic component scanning in the configuration.
+ * dynamic component scanning, and (when `context` is given) the lint
+ * target's own import graph.
  *
  * Resolution order:
  * 1. `config.files` — direct import of pretender data files
@@ -13,11 +26,14 @@ import { generalImport } from './general-import.js';
  * 3. `config.data` — inline pretender definitions
  * 4. `config.scan` — dynamic component scanning via glob patterns
  *    (`files` accepts `string | string[]`)
+ * 5. `config.auto` — on-demand scan of `context`'s own import graph (requires
+ *    `context`; a no-op without it, e.g. when the caller has no lint target yet)
  *
  * @param config - The pretenders configuration section from the optimized config
+ * @param context - The lint target's path/source, required only for `config.auto`
  * @returns An array of all resolved pretender definitions
  */
-export async function resolvePretenders(config) {
+export async function resolvePretenders(config, context) {
     if (!config) {
         return [];
     }
@@ -28,7 +44,9 @@ export async function resolvePretenders(config) {
             if (!pretenderFile?.data) {
                 continue;
             }
-            data.push(...pretenderFile.data);
+            // `file` is already absolute (resolved by the config provider), so its
+            // own directory is the correct base for the entries it carries.
+            data.push(...rebasePretenderFilePaths(pretenderFile.data, path.dirname(file)));
         }
     }
     if (config.imports) {
@@ -40,6 +58,10 @@ export async function resolvePretenders(config) {
             if (!pretenderFile?.data) {
                 continue;
             }
+            // The on-disk location of an npm package's pretenders data isn't
+            // recoverable from `generalImport`'s return value, so these entries'
+            // filePath is left as-is — disambiguation simply can't confirm them
+            // (see the module JSDoc for the fallback policy this implies).
             data.push(...pretenderFile.data);
         }
     }
@@ -56,9 +78,100 @@ export async function resolvePretenders(config) {
                 const scanned = await scan(resolved, {
                     ignoreComponentNames: entry.ignoreComponentNames ? [...entry.ignoreComponentNames] : undefined,
                 });
-                data.push(...scanned);
+                // `scan()` (with no `cwd` option) reports filePath relative to `process.cwd()`.
+                data.push(...rebasePretenderFilePaths(scanned, process.cwd()));
+            }
+        }
+    }
+    if (config.auto && context) {
+        const { autoScan } = await import('@markuplint/pretenders');
+        const scanned = await autoScan(context.filePath, context.sourceCode);
+        // `autoScan()` reports filePath relative to `process.cwd()`, same as `scan()`.
+        const rebased = rebasePretenderFilePaths(scanned, process.cwd());
+        // `scan` and `auto` can both walk into the same file (e.g. a component
+        // `scan`'s glob already covers that `auto`'s import-graph walk also
+        // reaches); de-duping on (selector, filePath) keeps that file's entry
+        // from appearing twice while still letting a same-selector entry from a
+        // genuinely different file through for `disambiguatePretendersForFile`
+        // to resolve. `selector` is a markuplint CSS-like selector and can
+        // legitimately contain spaces (a descendant combinator), so the pair is
+        // joined via `JSON.stringify` rather than a plain-string delimiter —
+        // otherwise two distinct (selector, filePath) pairs could concatenate to
+        // the same string and be mistaken for a duplicate.
+        const dedupeKey = (p) => JSON.stringify([p.selector, p.filePath]);
+        const seen = new Set(data.filter(p => p.filePath).map(p => dedupeKey(p)));
+        for (const pretender of rebased) {
+            if (pretender.filePath) {
+                const key = dedupeKey(pretender);
+                if (seen.has(key)) {
+                    continue;
+                }
+                seen.add(key);
             }
+            data.push(pretender);
         }
     }
     return data;
 }
+/**
+ * Resolves selector collisions in `pretenders` for the specific file about
+ * to be linted, deferring to `@markuplint/pretenders`' `disambiguatePretenders`
+ * only when there's actually a same-selector, file-backed collision to
+ * resolve — this keeps the common case (no ambiguity) free of both the
+ * dynamic import and any file/AST work.
+ *
+ * @param filePath - Absolute path of the file being linted
+ * @param sourceCode - Full source text of the file being linted
+ * @param pretenders - The flat pretender list {@link resolvePretenders} produced
+ * @returns The disambiguated pretender list, or `pretenders` itself (same
+ *   reference) when there was no collision to resolve
+ */
+export async function disambiguatePretendersForFile(filePath, sourceCode, pretenders) {
+    if (!hasResolvableCollision(pretenders)) {
+        return pretenders;
+    }
+    const { disambiguatePretenders } = await import('@markuplint/pretenders');
+    return disambiguatePretenders(pretenders, { filePath, sourceCode });
+}
+/**
+ * Deliberately gates on selector+filePath duplication alone — NOT on the
+ * selector name shape `@markuplint/pretenders`' `disambiguatePretenders`
+ * actually resolves (plain identifiers only). Duplicating that name-shape
+ * check here would let the two independently maintained filters drift out
+ * of sync: if the real filter is ever loosened without updating this one,
+ * this fast-path gate would keep skipping the dynamic import for cases the
+ * real logic would now handle, silently disabling disambiguation for them.
+ * Being a strict superset costs at most an unnecessary dynamic import for
+ * selectors the real logic ends up not touching — never a missed one.
+ *
+ * @param pretenders - The flat pretender list to check
+ * @returns `true` if some `selector` is shared by two or more `filePath`-backed entries
+ */
+export function hasResolvableCollision(pretenders) {
+    const seen = new Set();
+    for (const pretender of pretenders) {
+        if (!pretender.filePath) {
+            continue;
+        }
+        if (seen.has(pretender.selector)) {
+            return true;
+        }
+        seen.add(pretender.selector);
+    }
+    return false;
+}
+/**
+ * Clears `@markuplint/pretenders`' module-level import/export resolution
+ * caches. Call this whenever a lint host re-resolves config without cache
+ * (e.g. watch mode after a file change) — otherwise a renamed export or a
+ * 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.
+ *
+ * @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();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/file-resolver",
-	"version": "5.0.0-rc.4",
+	"version": "5.0.0-rc.6",
 	"description": "The file resolver of markuplint",
 	"repository": {
 		"type": "git",
@@ -10,7 +10,7 @@
 	"author": "Yusuke Hirao <yusukehirao@me.com>",
 	"license": "MIT",
 	"engines": {
-		"node": ">=22"
+		"node": ">=24"
 	},
 	"type": "module",
 	"exports": {
@@ -31,18 +31,18 @@
 		"clean": "tsc --build --clean"
 	},
 	"devDependencies": {
-		"@types/node": "24.5.1"
+		"@types/node": "24.13.3"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "5.0.0-rc.4",
-		"@markuplint/ml-ast": "5.0.0-rc.4",
-		"@markuplint/ml-config": "5.0.0-rc.4",
-		"@markuplint/ml-core": "5.0.0-rc.4",
-		"@markuplint/ml-spec": "5.0.0-rc.4",
-		"@markuplint/parser-utils": "5.0.0-rc.4",
-		"@markuplint/pretenders": "5.0.0-rc.4",
-		"@markuplint/selector": "5.0.0-rc.4",
-		"@markuplint/shared": "5.0.0-rc.4",
+		"@markuplint/html-parser": "5.0.0-rc.6",
+		"@markuplint/ml-ast": "5.0.0-rc.6",
+		"@markuplint/ml-config": "5.0.0-rc.6",
+		"@markuplint/ml-core": "5.0.0-rc.6",
+		"@markuplint/ml-spec": "5.0.0-rc.6",
+		"@markuplint/parser-utils": "5.0.0-rc.6",
+		"@markuplint/pretenders": "5.0.0-rc.6",
+		"@markuplint/selector": "5.0.0-rc.6",
+		"@markuplint/shared": "5.0.0-rc.6",
 		"cosmiconfig": "9.0.1",
 		"debug": "4.4.3",
 		"glob": "13.0.6",
@@ -51,5 +51,5 @@
 		"jsonc": "2.0.0",
 		"minimatch": "10.2.5"
 	},
-	"gitHead": "97a6339bbae23f556de5d307b3ce2ef7cfd9402d"
+	"gitHead": "c02c3a0783eac6b2fb4707be2dc00b88f6219641"
 }