@markuplint/file-resolver 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.3.0](https://github.com/markuplint/markuplint/compare/v5.2.0...v5.3.0) (2026-10-21)
+
+### Bug Fixes
+
+* **file-resolver:** cache the auto-load promise so a mid-load cache clear is not undone ([1f1b40e](https://github.com/markuplint/markuplint/commit/1f1b40e4020dfe51310f73e7c89bc887a4ad04d4))
+* **file-resolver:** pass the working directory to the lint-time disambiguation ([542cc62](https://github.com/markuplint/markuplint/commit/542cc6272ab8922116bda7d87bb4c9ccb984c3f1)), closes [#4269](https://github.com/markuplint/markuplint/issues/4269)
+* **file-resolver:** resolve a lone scanned component against the file's imports ([c37e922](https://github.com/markuplint/markuplint/commit/c37e922eed92876dd963dd74e9990a4a0da68ccc))
+* make published packages loadable from require() and put types first ([723106f](https://github.com/markuplint/markuplint/commit/723106f51aac4e60dc02db2c1a894617368b0253)), closes [#4198](https://github.com/markuplint/markuplint/issues/4198)
+
+### Performance Improvements
+
+* **file-resolver:** cache auto-load misses to skip repeated module resolution ([91931ca](https://github.com/markuplint/markuplint/commit/91931caf078c815c0e456dde51f0230b6d782c9d))
+* **file-resolver:** group the config search debug calls under one guard ([0353e02](https://github.com/markuplint/markuplint/commit/0353e029f79471b8b5495a4ae83edea58ab8cfe3))
+
+
 # [5.2.0](https://github.com/markuplint/markuplint/compare/v5.1.1...v5.2.0) (2026-10-13)
 
 ### Bug Fixes

package/lib/auto-load-rules.d.ts

@@ -1,4 +1,5 @@
 import type { Ruleset, AnyMLRule } from '@markuplint/ml-core';
+export declare function clearAutoLoadRulesCache(): void;
 export declare function autoLoadRules(ruleset: Ruleset): Promise<{
     rules: AnyMLRule[];
     errors: unknown[];

package/lib/auto-load-rules.js

@@ -1,58 +1,53 @@
 import { MLRule } from '@markuplint/ml-core';
+/**
+ * Keyed by rule name, holding the in-flight or settled load. A miss stays
+ * cached (`rule: null`, with the errors each probe raised) until
+ * {@link clearAutoLoadRulesCache}: this runs once per linted file and built-in
+ * rule names never resolve to a package, so re-probing would cost two failing
+ * imports per rule per file. Same lifetime policy as `generalImport`'s cache,
+ * which never retries a miss either.
+ *
+ * The entry is set synchronously before the first `await`, so a
+ * `clearAutoLoadRulesCache()` that lands mid-load evicts the promise and the
+ * eventual result is never written back into the fresh map.
+ */
 const cache = new Map();
+export function clearAutoLoadRulesCache() {
+    cache.clear();
+}
 export async function autoLoadRules(ruleset) {
     const rules = [];
     const errors = [];
     for (const ruleName of Object.keys(ruleset.rules)) {
-        const cached = cache.get(ruleName);
-        if (cached) {
-            rules.push(cached);
-            continue;
-        }
-        let seed = null;
-        try {
-            const _module = await import(`@markuplint/rule-${ruleName}`);
-            seed = _module.default;
-            if (!(seed && 'defaultValue' in seed && 'defaultOptions' in seed && 'verify' in seed)) {
-                seed = null;
-            }
-        }
-        catch (error) {
-            errors.push(error);
+        let loading = cache.get(ruleName);
+        if (!loading) {
+            loading = load(ruleName);
+            cache.set(ruleName, loading);
         }
-        if (seed) {
-            const rule = new MLRule({
-                name: ruleName,
-                ...seed,
-            });
-            cache.set(ruleName, rule);
-            rules.push(rule);
-            continue;
+        const loaded = await loading;
+        if (loaded.rule) {
+            rules.push(loaded.rule);
         }
+        errors.push(...loaded.errors);
+    }
+    return { rules, errors };
+}
+async function load(ruleName) {
+    const errors = [];
+    for (const specifier of [`@markuplint/rule-${ruleName}`, `markuplint-rule-${ruleName}`]) {
         try {
-            const _module = await import(`markuplint-rule-${ruleName}`);
-            seed = _module.default;
-            if (!(seed && 'defaultValue' in seed && 'defaultOptions' in seed && 'verify' in seed)) {
-                seed = null;
+            const mod = await import(specifier);
+            const seed = mod.default;
+            if (isRuleSeed(seed)) {
+                return { rule: new MLRule({ name: ruleName, ...seed }), errors };
             }
         }
         catch (error) {
             errors.push(error);
         }
-        if (seed) {
-            const rule = new MLRule({
-                name: ruleName,
-                ...seed,
-            });
-            cache.set(ruleName, rule);
-            rules.push(rule);
-            continue;
-        }
     }
-    return {
-        // Clone
-        rules: [...rules],
-        // Clone
-        errors: [...errors],
-    };
+    return { rule: null, errors };
+}
+function isRuleSeed(seed) {
+    return !!seed && typeof seed === 'object' && 'defaultValue' in seed && 'defaultOptions' in seed && 'verify' in seed;
 }

package/lib/config-provider.d.ts

@@ -21,16 +21,19 @@ export declare class ConfigProvider {
      * 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).
+     * module-level plugin-resolution cache, `auto-load-rules.ts`'s rule
+     * 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.
+     * The `cosmiconfig` explorer and the `resolve-plugins.ts` /
+     * `auto-load-rules.ts` caches are module-level singletons shared by every
+     * `ConfigProvider` instance in the process — clearing them here affects
+     * other instances too, not just this one. Correctness is unaffected (they
+     * just re-search/re-load), but the auto-load cache holds a miss for every
+     * built-in rule name, so the first lint after a clear repeats two failing
+     * imports per rule — 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

package/lib/config-provider.js

@@ -3,6 +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 { clearAutoLoadRulesCache } from './auto-load-rules.js';
 import { load as loadConfig, search, clearExplorerCache } from './cosmiconfig.js';
 import { log } from './debug.js';
 import { generalImport } from './general-import.js';
@@ -52,16 +53,19 @@ export class ConfigProvider {
      * 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).
+     * module-level plugin-resolution cache, `auto-load-rules.ts`'s rule
+     * 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.
+     * The `cosmiconfig` explorer and the `resolve-plugins.ts` /
+     * `auto-load-rules.ts` caches are module-level singletons shared by every
+     * `ConfigProvider` instance in the process — clearing them here affects
+     * other instances too, not just this one. Correctness is unaffected (they
+     * just re-search/re-load), but the auto-load cache holds a miss for every
+     * built-in rule name, so the first lint after a clear repeats two failing
+     * imports per rule — 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
@@ -77,6 +81,7 @@ export class ConfigProvider {
         this.#cache.clear();
         this.#autoKeys = new WeakMap();
         cacheClear();
+        clearAutoLoadRulesCache();
         clearExplorerCache();
     }
     /**
@@ -265,8 +270,10 @@ export class ConfigProvider {
      */
     async search(targetFile) {
         const isExists = await targetFile.dirExists();
-        cpLog('search: %s', targetFile.path);
-        cpLog('isExists: %s', isExists);
+        if (cpLog.enabled) {
+            cpLog('search: %s', targetFile.path);
+            cpLog('isExists: %s', isExists);
+        }
         if (!isExists) {
             return null;
         }

package/lib/debug.d.ts

@@ -1,3 +1,7 @@
 import debug from 'debug';
 export type Log = debug.Debugger;
+/**
+ * Read `.enabled` at call time; never cache it at module load. `debug.enable()` (including via `verbosely()` /
+ * `enableDebug()`) can switch a namespace on after import.
+ */
 export declare const log: debug.Debugger;

package/lib/debug.js

@@ -1,2 +1,6 @@
 import debug from 'debug';
+/**
+ * Read `.enabled` at call time; never cache it at module load. `debug.enable()` (including via `verbosely()` /
+ * `enableDebug()`) can switch a namespace on after import.
+ */
 export const log = debug('ml-fr');

package/lib/resolve-pretenders.d.ts

@@ -101,31 +101,30 @@ export declare function createPretenderResolver(config: PretendersConfig): Prete
  */
 export declare function resolvePretenders(config: PretendersConfig, context?: ResolvePretendersContext, options?: ResolvePretendersOptions): 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.
+ * Resolves, for the specific file about to be linted, which of the
+ * file-backed `pretenders` it actually refers to — a selector shared by
+ * several of them, and a name it imports from a package (a lone entry
+ * included, as it may be a package's component that shares the name) — by
+ * deferring to `@markuplint/pretenders`' `disambiguatePretenders`. Without a
+ * file-backed entry there is nothing to resolve, which keeps that common case
+ * free of the dynamic import; `disambiguatePretenders` itself skips the
+ * file/AST work for a source that names none of them.
  *
  * @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
  * @param options - Where to report the files the result depends on
  * @returns The disambiguated pretender list, or `pretenders` itself (same
- *   reference) when there was no collision to resolve
+ *   reference) when there was nothing to resolve
  */
 export declare function disambiguatePretendersForFile(filePath: string, sourceCode: string, pretenders: readonly Pretender[], options?: ResolvePretendersOptions): 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.
+ * Whether two or more `filePath`-backed entries share a selector, whatever the
+ * selector name shape.
  *
+ * @deprecated Nothing in markuplint calls it any more, and it has no replacement:
+ *   {@link disambiguatePretendersForFile} decides by itself whether there is anything
+ *   to resolve. To be removed in the next major version.
  * @param pretenders - The flat pretender list to check
  * @returns `true` if some `selector` is shared by two or more `filePath`-backed entries
  */

package/lib/resolve-pretenders.js

@@ -164,37 +164,42 @@ async function appendAutoPretenders(data, context, auto, dependencies) {
     }
 }
 /**
- * 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.
+ * Resolves, for the specific file about to be linted, which of the
+ * file-backed `pretenders` it actually refers to — a selector shared by
+ * several of them, and a name it imports from a package (a lone entry
+ * included, as it may be a package's component that shares the name) — by
+ * deferring to `@markuplint/pretenders`' `disambiguatePretenders`. Without a
+ * file-backed entry there is nothing to resolve, which keeps that common case
+ * free of the dynamic import; `disambiguatePretenders` itself skips the
+ * file/AST work for a source that names none of them.
  *
  * @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
  * @param options - Where to report the files the result depends on
  * @returns The disambiguated pretender list, or `pretenders` itself (same
- *   reference) when there was no collision to resolve
+ *   reference) when there was nothing to resolve
  */
 export async function disambiguatePretendersForFile(filePath, sourceCode, pretenders, options) {
-    if (!hasResolvableCollision(pretenders)) {
+    if (!pretenders.some(pretender => pretender.filePath)) {
         return pretenders;
     }
     const { disambiguatePretenders } = await import('@markuplint/pretenders');
-    return disambiguatePretenders(pretenders, { filePath, sourceCode, dependencies: options?.dependencies });
+    // The same base the scanned pretenders' paths were made absolute from (see `rebasePretenderFilePaths`).
+    return disambiguatePretenders(pretenders, {
+        filePath,
+        sourceCode,
+        dependencies: options?.dependencies,
+        cwd: process.cwd(),
+    });
 }
 /**
- * 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.
+ * Whether two or more `filePath`-backed entries share a selector, whatever the
+ * selector name shape.
  *
+ * @deprecated Nothing in markuplint calls it any more, and it has no replacement:
+ *   {@link disambiguatePretendersForFile} decides by itself whether there is anything
+ *   to resolve. To be removed in the next major version.
  * @param pretenders - The flat pretender list to check
  * @returns `true` if some `selector` is shared by two or more `filePath`-backed entries
  */

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/file-resolver",
-	"version": "5.2.0",
+	"version": "5.3.0",
 	"description": "The file resolver of markuplint",
 	"repository": {
 		"type": "git",
@@ -15,8 +15,8 @@
 	"type": "module",
 	"exports": {
 		".": {
-			"import": "./lib/index.js",
-			"types": "./lib/index.d.ts"
+			"types": "./lib/index.d.ts",
+			"default": "./lib/index.js"
 		}
 	},
 	"publishConfig": {
@@ -31,25 +31,25 @@
 		"clean": "tsc --build --clean"
 	},
 	"devDependencies": {
-		"@types/node": "24.19.1"
+		"@types/node": "24.19.2"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "5.2.0",
-		"@markuplint/ml-ast": "5.1.1",
-		"@markuplint/ml-config": "5.2.0",
-		"@markuplint/ml-core": "5.2.0",
-		"@markuplint/ml-spec": "5.2.0",
-		"@markuplint/parser-utils": "5.2.0",
-		"@markuplint/pretenders": "5.2.0",
-		"@markuplint/selector": "5.2.0",
-		"@markuplint/shared": "5.2.0",
-		"cosmiconfig": "^9.0.2",
+		"@markuplint/html-parser": "5.3.0",
+		"@markuplint/ml-ast": "5.3.0",
+		"@markuplint/ml-config": "5.3.0",
+		"@markuplint/ml-core": "5.3.0",
+		"@markuplint/ml-spec": "5.3.0",
+		"@markuplint/parser-utils": "5.3.0",
+		"@markuplint/pretenders": "5.3.0",
+		"@markuplint/selector": "5.3.0",
+		"@markuplint/shared": "5.3.0",
+		"cosmiconfig": "^10.0.1",
 		"debug": "^4.4.3",
 		"glob": "^13.0.6",
 		"ignore": "^7.0.12",
 		"import-meta-resolve": "^4.2.0",
-		"jsonc": "^2.0.0",
+		"jsonc": "^3.0.0",
 		"minimatch": "^10.2.6"
 	},
-	"gitHead": "d8b2feab77c9c862513615bea6b80d2817431878"
+	"gitHead": "f587cf0206c8426e57369a48d6d5fb22306eafde"
 }