@markuplint/file-resolver 5.0.0-rc.5 → 5.0.0-rc.7

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 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.7](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.6...v5.0.0-rc.7) (2026-08-31)
+
+### Features
+
+- **file-resolver:** record which overrides globs matched a target file ([c4cba6d](https://github.com/markuplint/markuplint/commit/c4cba6d9444ecb19752204a1655caad0d27f3ff8)), closes [#4023](https://github.com/markuplint/markuplint/issues/4023)
+
+# [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

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,43 @@ 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.
+     *
+     * Matches are applied in `Object.keys(overrides)` order (config-key insertion
+     * order), each round re-assigning `config` rather than accumulating — so under
+     * the default `overrideMode: 'reset'`, the last-matching glob's config entirely
+     * 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).
+     */
+    #applyOverrides(baseConfigSet, targetFile) {
+        let config = baseConfigSet.config;
+        const appliedOverrides = [];
+        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;
+                    appliedOverrides.push(glob);
+                }
+            }
+            return config === baseConfigSet.config ? baseConfigSet : { ...baseConfigSet, config, appliedOverrides };
+        }
+        return baseConfigSet;
     }
     /**
      * Searches for a markuplint configuration file starting from the target file's directory.
@@ -180,12 +286,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/types.d.ts

@@ -13,6 +13,15 @@ export interface ConfigSet {
     readonly files: ReadonlySet<string>;
     /** Errors encountered during config loading or resolution */
     readonly errs: readonly Readonly<Error>[];
+    /**
+     * `overrides` keys (resolved to absolute globs by `OptimizedConfig`) that
+     * matched the target file, in the order they were applied — config-key
+     * order, so later entries win under `overrideMode: 'reset'`, the default.
+     * Absent — never an empty array — when no override matched this target
+     * file, whether because the config has no `overrides` at all or none of
+     * its globs matched.
+     */
+    readonly appliedOverrides?: readonly string[];
 }
 /**
  * A lint target: either a file path/glob string, or an inline source code object.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/file-resolver",
-	"version": "5.0.0-rc.5",
+	"version": "5.0.0-rc.7",
 	"description": "The file resolver of markuplint",
 	"repository": {
 		"type": "git",
@@ -34,15 +34,15 @@
 		"@types/node": "24.13.3"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "5.0.0-rc.5",
-		"@markuplint/ml-ast": "5.0.0-rc.5",
-		"@markuplint/ml-config": "5.0.0-rc.5",
-		"@markuplint/ml-core": "5.0.0-rc.5",
-		"@markuplint/ml-spec": "5.0.0-rc.5",
-		"@markuplint/parser-utils": "5.0.0-rc.5",
-		"@markuplint/pretenders": "5.0.0-rc.5",
-		"@markuplint/selector": "5.0.0-rc.5",
-		"@markuplint/shared": "5.0.0-rc.5",
+		"@markuplint/html-parser": "5.0.0-rc.7",
+		"@markuplint/ml-ast": "5.0.0-rc.7",
+		"@markuplint/ml-config": "5.0.0-rc.7",
+		"@markuplint/ml-core": "5.0.0-rc.7",
+		"@markuplint/ml-spec": "5.0.0-rc.7",
+		"@markuplint/parser-utils": "5.0.0-rc.7",
+		"@markuplint/pretenders": "5.0.0-rc.7",
+		"@markuplint/selector": "5.0.0-rc.7",
+		"@markuplint/shared": "5.0.0-rc.7",
 		"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": "8d87463af2ff3f1b83fb28da20f1819362cf3555"
+	"gitHead": "8d7a3b801e0f5f88438c003e7eee2bd45e6aedd0"
 }