@markuplint/file-resolver 5.3.0 → 5.5.0

package/lib/import-module.d.ts

@@ -0,0 +1,28 @@
+/**
+ * `import()` that takes a JSON module as one. Node.js and Deno load a JSON module through
+ * `import()` only with the import attribute `type: 'json'` (Bun takes it either way), and a
+ * module that a configuration names can be one, a configuration to `extends` or the data of
+ * `pretenders`, with or without the `.json` extension, as the `exports` map of a package can
+ * redirect a specifier. The attribute cannot be given up front, as a `.json` specifier can be
+ * redirected to a JavaScript module the same way, and the attribute would then be rejected; and
+ * Deno rejects a dynamic `import()` with the attribute as it rejects one without. So the
+ * specifier is imported as it is, and when the runtime reports a JSON module without the
+ * attribute ({@link isJsonWithoutAttribute}), or the `.json` extension says so, it is
+ * `require()`d instead: CommonJS takes a JSON module as it is on every runtime, a bare specifier
+ * and a path alike, and what it returns is handed over as the default export, the shape
+ * `import()` gives a JSON module. Any other failure of `import()` is thrown as it is, as that is
+ * what the callers read (a package that is not installed, a subpath that `exports` does not
+ * expose), and `require()` would only run the module's code again. The report is read before the
+ * code of a missing module, as Deno attaches that code to the report as well; the code decides
+ * only for a `.json` specifier that the runtime did not report as JSON.
+ *
+ * The `catch` is not guarded by `isFatalError()`: the runtimes report the missing attribute with
+ * a `TypeError`, which the guard would re-throw before the retry.
+ *
+ * @param specifier - What `import()` takes: a bare specifier, a `file:` URL, or an absolute path
+ *   as `moduleExists()` passes it (a Windows drive path fails here and is left to its
+ *   `require.resolve()`)
+ * @returns The module namespace that `import()` resolves to, or `{ default }` of what
+ *   `require()` returns for a JSON module
+ */
+export declare function importModule(specifier: string): Promise<Record<string, unknown>>;

package/lib/import-module.js

@@ -0,0 +1,64 @@
+import { createRequire } from 'node:module';
+import { isModuleNotFoundError } from '@markuplint/shared';
+import { log } from './debug.js';
+import { fromFileURL } from './path-utils.js';
+const require = createRequire(import.meta.url);
+const iLog = log.extend('import-module');
+/**
+ * `import()` that takes a JSON module as one. Node.js and Deno load a JSON module through
+ * `import()` only with the import attribute `type: 'json'` (Bun takes it either way), and a
+ * module that a configuration names can be one, a configuration to `extends` or the data of
+ * `pretenders`, with or without the `.json` extension, as the `exports` map of a package can
+ * redirect a specifier. The attribute cannot be given up front, as a `.json` specifier can be
+ * redirected to a JavaScript module the same way, and the attribute would then be rejected; and
+ * Deno rejects a dynamic `import()` with the attribute as it rejects one without. So the
+ * specifier is imported as it is, and when the runtime reports a JSON module without the
+ * attribute ({@link isJsonWithoutAttribute}), or the `.json` extension says so, it is
+ * `require()`d instead: CommonJS takes a JSON module as it is on every runtime, a bare specifier
+ * and a path alike, and what it returns is handed over as the default export, the shape
+ * `import()` gives a JSON module. Any other failure of `import()` is thrown as it is, as that is
+ * what the callers read (a package that is not installed, a subpath that `exports` does not
+ * expose), and `require()` would only run the module's code again. The report is read before the
+ * code of a missing module, as Deno attaches that code to the report as well; the code decides
+ * only for a `.json` specifier that the runtime did not report as JSON.
+ *
+ * The `catch` is not guarded by `isFatalError()`: the runtimes report the missing attribute with
+ * a `TypeError`, which the guard would re-throw before the retry.
+ *
+ * @param specifier - What `import()` takes: a bare specifier, a `file:` URL, or an absolute path
+ *   as `moduleExists()` passes it (a Windows drive path fails here and is left to its
+ *   `require.resolve()`)
+ * @returns The module namespace that `import()` resolves to, or `{ default }` of what
+ *   `require()` returns for a JSON module
+ */
+export async function importModule(specifier) {
+    try {
+        return await import(specifier);
+    }
+    catch (error) {
+        const isJson = isJsonWithoutAttribute(error) || (specifier.endsWith('.json') && !isModuleNotFoundError(error));
+        if (!isJson) {
+            throw error;
+        }
+        iLog('`import()` refused %s as a JSON module (%O); taking `require()`', specifier, error);
+        return { default: require(specifier.startsWith('file:') ? fromFileURL(specifier) : specifier) };
+    }
+}
+/**
+ * Whether `import()` reported that the module is JSON and the attribute was not given. The
+ * wording is each runtime's own, observed in `general-import.runtime.spec.ts` in a fresh process
+ * of the runtime that runs the specs:
+ *
+ * - Node.js: the code `ERR_IMPORT_ATTRIBUTE_MISSING`
+ * - Deno: `Attempted to load JSON module without specifying "type": "json" attribute in the
+ *   import statement.`
+ * - Bun: never, as it takes a JSON module without the attribute
+ *
+ * @param error - What `import()` threw
+ * @returns `true` for that report
+ */
+function isJsonWithoutAttribute(error) {
+    return (error instanceof Error &&
+        (('code' in error && error.code === 'ERR_IMPORT_ATTRIBUTE_MISSING') ||
+            error.message.startsWith('Attempted to load JSON module without specifying "type": "json" attribute')));
+}

package/lib/index.d.ts

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

package/lib/index.js

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

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

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

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

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

package/lib/module-exists.d.ts

@@ -1 +1,23 @@
+/**
+ * Whether `name` resolves to a module from where markuplint is installed: a package, or a file of
+ * one, as `extends`, `plugins`, `parser` and `specs` take a module.
+ *
+ * The resolution is that of this file's own location, as `import()` and `createRequire()` do it,
+ * never that of the configuration file that names the module, so a relative path is not a module
+ * here and is answered `false` without asking the runtime: resolved from this file, it would reach
+ * this package's own files or whatever lies above them. `resolveNameOrAbsPath` keeps a value
+ * spelled as a path away in the first place; `ConfigProvider` passes the names it is given as they
+ * are, so a relative one is answered `false` here and rejected as not absolute by its `#load`.
+ *
+ * The `catch` is not guarded by `isFatalError()`: what `import()` throws comes from the runtime's
+ * loader, which reports a file it cannot take as a module with a `SyntaxError` or a `TypeError`.
+ * Vite's module runner, which Vitest runs the specs in, reports such a file as a `Parse failure`,
+ * and that alone proves the file resolves; after any other failure the specifier is asked of
+ * `require.resolve()`, and what that throws, besides the module being absent or unexposed, is
+ * re-thrown as it is.
+ *
+ * @param name - A bare specifier, or an absolute path
+ * @returns `true` when the module resolves, including a file that the package's `exports` do not
+ *   expose, and a file that resolves but cannot be imported; `false` for a relative path
+ */
 export declare function moduleExists(name: string): Promise<boolean>;

package/lib/module-exists.js

@@ -1,21 +1,39 @@
 import { createRequire } from 'node:module';
 import { log } from './debug.js';
+import { importModule } from './import-module.js';
+import { isRelativePath } from './path-utils.js';
 const require = createRequire(import.meta.url);
 const mLog = log.extend('module-exists');
+/**
+ * Whether `name` resolves to a module from where markuplint is installed: a package, or a file of
+ * one, as `extends`, `plugins`, `parser` and `specs` take a module.
+ *
+ * The resolution is that of this file's own location, as `import()` and `createRequire()` do it,
+ * never that of the configuration file that names the module, so a relative path is not a module
+ * here and is answered `false` without asking the runtime: resolved from this file, it would reach
+ * this package's own files or whatever lies above them. `resolveNameOrAbsPath` keeps a value
+ * spelled as a path away in the first place; `ConfigProvider` passes the names it is given as they
+ * are, so a relative one is answered `false` here and rejected as not absolute by its `#load`.
+ *
+ * The `catch` is not guarded by `isFatalError()`: what `import()` throws comes from the runtime's
+ * loader, which reports a file it cannot take as a module with a `SyntaxError` or a `TypeError`.
+ * Vite's module runner, which Vitest runs the specs in, reports such a file as a `Parse failure`,
+ * and that alone proves the file resolves; after any other failure the specifier is asked of
+ * `require.resolve()`, and what that throws, besides the module being absent or unexposed, is
+ * re-thrown as it is.
+ *
+ * @param name - A bare specifier, or an absolute path
+ * @returns `true` when the module resolves, including a file that the package's `exports` do not
+ *   expose, and a file that resolves but cannot be imported; `false` for a relative path
+ */
 export async function moduleExists(name) {
+    if (isRelativePath(name)) {
+        return false;
+    }
     try {
-        await import(name);
+        await importModule(name);
     }
     catch (error) {
-        if (
-        // @ts-ignore
-        'code' in error &&
-            // @ts-ignore
-            error.code === 'ERR_IMPORT_ASSERTION_TYPE_MISSING') {
-            // It exists, but it is may be a JSON file.
-            mLog('Return true, but it caught Error in `import()`: %O', error);
-            return true;
-        }
         if (error instanceof Error && /^parse failure/i.test(error.message)) {
             // It exists, but it failed to parse.
             mLog('Return true, but it caught Error in `import()`: %O', error);

package/lib/path-to-abs-or-name.d.ts

@@ -1 +1,19 @@
+/**
+ * Applies {@link resolveNameOrAbsPath} to a property of a configuration in whichever shape it
+ * takes: one value, a list of values, or a map such as `parser` (an extension to a module or a
+ * file) and `overrides` (a glob to a configuration).
+ *
+ * In a map, or in an entry of a list, every string value is resolved unless `resolveProps` names
+ * the properties that hold a path, as `name` is the one of a `plugins` entry. The keys are left
+ * alone unless `resolveKey` says they are paths, as the globs of `overrides` are; the values of
+ * `overrides` are configurations in turn, which the caller resolves one by one.
+ *
+ * @template T - The shape of the property
+ * @param dir - The directory of the configuration file that declares the property
+ * @param filePath - The property, or `undefined` when the configuration does not hold it
+ * @param resolveProps - The properties of a map, or of an entry of a list, whose values are paths;
+ *   every string value is one when omitted
+ * @param resolveKey - Whether the keys of a map are paths
+ * @returns The property with its paths resolved, in the same shape, or `undefined` as given
+ */
 export declare function relPathToNameOrAbsPath<T extends string | readonly (string | Record<string, unknown>)[] | Readonly<Record<string, unknown>> | undefined>(dir: string, filePath?: T, resolveProps?: readonly string[], resolveKey?: boolean): Promise<T>;

package/lib/path-to-abs-or-name.js

@@ -1,4 +1,22 @@
 import { resolveNameOrAbsPath } from './resolve-name-or-abs-path.js';
+/**
+ * Applies {@link resolveNameOrAbsPath} to a property of a configuration in whichever shape it
+ * takes: one value, a list of values, or a map such as `parser` (an extension to a module or a
+ * file) and `overrides` (a glob to a configuration).
+ *
+ * In a map, or in an entry of a list, every string value is resolved unless `resolveProps` names
+ * the properties that hold a path, as `name` is the one of a `plugins` entry. The keys are left
+ * alone unless `resolveKey` says they are paths, as the globs of `overrides` are; the values of
+ * `overrides` are configurations in turn, which the caller resolves one by one.
+ *
+ * @template T - The shape of the property
+ * @param dir - The directory of the configuration file that declares the property
+ * @param filePath - The property, or `undefined` when the configuration does not hold it
+ * @param resolveProps - The properties of a map, or of an entry of a list, whose values are paths;
+ *   every string value is one when omitted
+ * @param resolveKey - Whether the keys of a map are paths
+ * @returns The property with its paths resolved, in the same shape, or `undefined` as given
+ */
 export async function relPathToNameOrAbsPath(dir, filePath, resolveProps, resolveKey = false) {
     if (filePath == null) {
         // @ts-ignore

package/lib/path-utils.d.ts

@@ -31,3 +31,12 @@ export declare function toFileURL(filePath: string): string;
 export declare function normalizeForIgnore(filePath: string, relative?: boolean): string;
 /** Glob libraries require forward slashes. */
 export declare function normalizeForGlob(filePath: string): string;
+/**
+ * Whether `filePath` is written as a relative path: a `.` or `..` segment first, followed by
+ * either separator (`./x`, `../x`, `.\x`, `..\x`) or by nothing (`.`, `..`). A dot-file name such
+ * as `.markuplintrc` is not one.
+ *
+ * @param filePath - A value of a configuration that names a file or a module
+ * @returns `true` for a relative path
+ */
+export declare function isRelativePath(filePath: string): boolean;

package/lib/path-utils.js

@@ -76,3 +76,14 @@ export function normalizeForIgnore(filePath, relative = false) {
 export function normalizeForGlob(filePath) {
     return toSlash(filePath);
 }
+/**
+ * Whether `filePath` is written as a relative path: a `.` or `..` segment first, followed by
+ * either separator (`./x`, `../x`, `.\x`, `..\x`) or by nothing (`.`, `..`). A dot-file name such
+ * as `.markuplintrc` is not one.
+ *
+ * @param filePath - A value of a configuration that names a file or a module
+ * @returns `true` for a relative path
+ */
+export function isRelativePath(filePath) {
+    return /^\.\.?(?:[/\\]|$)/.test(filePath);
+}

package/lib/resolve-name-or-abs-path.d.ts

@@ -1 +1,19 @@
+/**
+ * Resolves a value of a configuration that names a module or a file: a module name stays as it
+ * is, and a path becomes absolute against `dir`.
+ *
+ * A value spelled as a path (`./`, `../`, `.`, `..`, with either separator, or absolute) and a
+ * value with the `!` prefix of an exclusion are resolved without asking `moduleExists()`, which
+ * resolves a relative specifier from where markuplint is installed, not from the configuration: a
+ * file by that name there would make the value a module, keep it relative, and have it read from
+ * the working directory later. Installed in a project's `node_modules`, this package's `lib/` lies
+ * four directories below the project root (`node_modules/@markuplint/file-resolver/lib/`), so a
+ * configuration four directories below the root collided with the root's own `.markuplintrc`
+ * through `../../../../.markuplintrc`, and `../package.json` names this package's own. Any other
+ * value is tried as a module first, as the documentation of `extends` and its kin describes.
+ *
+ * @param dir - The directory of the configuration file that declares the value
+ * @param pathOrModName - The value, possibly with the `!` prefix of an exclusion
+ * @returns The module name as it is, or the absolute path, with the `!` prefix kept
+ */
 export declare function resolveNameOrAbsPath(dir: string, pathOrModName: string): Promise<string>;

package/lib/resolve-name-or-abs-path.js

@@ -2,13 +2,32 @@ import path from 'node:path';
 import { isPluginModuleName } from './is-plugin-module-name.js';
 import { isPresetModuleName } from './is-preset-module-name.js';
 import { moduleExists } from './module-exists.js';
+import { isRelativePath } from './path-utils.js';
+/**
+ * Resolves a value of a configuration that names a module or a file: a module name stays as it
+ * is, and a path becomes absolute against `dir`.
+ *
+ * A value spelled as a path (`./`, `../`, `.`, `..`, with either separator, or absolute) and a
+ * value with the `!` prefix of an exclusion are resolved without asking `moduleExists()`, which
+ * resolves a relative specifier from where markuplint is installed, not from the configuration: a
+ * file by that name there would make the value a module, keep it relative, and have it read from
+ * the working directory later. Installed in a project's `node_modules`, this package's `lib/` lies
+ * four directories below the project root (`node_modules/@markuplint/file-resolver/lib/`), so a
+ * configuration four directories below the root collided with the root's own `.markuplintrc`
+ * through `../../../../.markuplintrc`, and `../package.json` names this package's own. Any other
+ * value is tried as a module first, as the documentation of `extends` and its kin describes.
+ *
+ * @param dir - The directory of the configuration file that declares the value
+ * @param pathOrModName - The value, possibly with the `!` prefix of an exclusion
+ * @returns The module name as it is, or the absolute path, with the `!` prefix kept
+ */
 export async function resolveNameOrAbsPath(dir, pathOrModName) {
-    if ((await moduleExists(pathOrModName)) || isPresetModuleName(pathOrModName) || isPluginModuleName(pathOrModName)) {
-        return pathOrModName;
-    }
     const bangAndPath = /^(!)(.*)/.exec(pathOrModName) ?? [];
     const bang = bangAndPath[1] ?? '';
     const pathname = bangAndPath[2] ?? pathOrModName;
-    const absPath = path.resolve(dir, pathname);
-    return bang + absPath;
+    const isPath = bang !== '' || path.isAbsolute(pathname) || isRelativePath(pathname);
+    if (!isPath && (isPresetModuleName(pathname) || isPluginModuleName(pathname) || (await moduleExists(pathname)))) {
+        return pathOrModName;
+    }
+    return bang + path.resolve(dir, pathname);
 }

package/lib/resolve-pretenders.d.ts

@@ -60,6 +60,8 @@ export type PretenderResolver = {
      *   only on the call that read them.
      * @returns All resolved pretender definitions — a new array on every call,
      *   so the retained target-independent entries are never exposed to mutation
+     * @throws An `Error` that says how to install `@markuplint/pretenders` when `config.scan`
+     *   or `config.auto` needs it and it is not installed, with the error of the import as its `cause`
      */
     resolve(context?: ResolvePretendersContext, options?: ResolvePretendersOptions): Promise<Pretender[]>;
 };
@@ -70,7 +72,8 @@ export type PretenderResolver = {
  * kept as well — the host's next config resolution creates a new resolver).
  *
  * @param config - The pretenders configuration section from the optimized config
- * @returns The resolver; its `resolve()` yields `[]` when `config` is absent
+ * @returns The resolver; its `resolve()` yields `[]` when `config` is absent, and rejects as
+ *   {@link resolvePretenders} does when `@markuplint/pretenders` is needed and not installed
  */
 export declare function createPretenderResolver(config: PretendersConfig): PretenderResolver;
 /**
@@ -98,6 +101,10 @@ export declare function createPretenderResolver(config: PretendersConfig): Prete
  * @param context - The lint target's path/source, required only for `config.auto`
  * @param options - Where to report the files the result depends on
  * @returns An array of all resolved pretender definitions
+ * @throws An `Error` that says how to install `@markuplint/pretenders` when `config.scan` or
+ *   `config.auto` needs it and it is not installed (an optional peer of this package), with the
+ *   error of the import as its `cause`. A module that an installed `@markuplint/pretenders`
+ *   needs being missing is thrown as it is.
  */
 export declare function resolvePretenders(config: PretendersConfig, context?: ResolvePretendersContext, options?: ResolvePretendersOptions): Promise<Pretender[]>;
 /**
@@ -116,6 +123,8 @@ export declare function resolvePretenders(config: PretendersConfig, context?: Re
  * @param options - Where to report the files the result depends on
  * @returns The disambiguated pretender list, or `pretenders` itself (same
  *   reference) when there was nothing to resolve
+ * @throws An `Error` that says how to install `@markuplint/pretenders` when an entry has a
+ *   `filePath` and it is not installed, with the error of the import as its `cause`
  */
 export declare function disambiguatePretendersForFile(filePath: string, sourceCode: string, pretenders: readonly Pretender[], options?: ResolvePretendersOptions): Promise<readonly Pretender[]>;
 /**
@@ -136,7 +145,8 @@ export declare function hasResolvableCollision(pretenders: readonly Pretender[])
  * 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.
+ * caches in that case either, and when it is installed but fails to load, which
+ * is logged under the `ml-fr` debug namespace: what needs it fails on its own, with the reason.
  *
  * @returns A promise that resolves once the caches have been cleared
  */

package/lib/resolve-pretenders.js

@@ -1,11 +1,43 @@
 import path from 'node:path';
-import { rebasePretenderFilePath } from '@markuplint/ml-config';
+import { rebaseHandWrittenPretenderFilePath, rebasePretenderFilePath } from '@markuplint/ml-config';
+import { isFatalError, missingPackageOf } from '@markuplint/shared';
 import { glob } from 'glob';
+import { log } from './debug.js';
 import { generalImport } from './general-import.js';
+import { normalizeForGlob } from './path-utils.js';
+const PRETENDERS_PACKAGE = '@markuplint/pretenders';
 /**
- * `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.
+ * `@markuplint/pretenders` is an optional peer of this package (`peerDependenciesMeta`): installing markuplint
+ * does not install it, nor the parsers and the frameworks behind them, so it is loaded only for a
+ * configuration that needs it, and one that does is told how to install it rather than given the bare
+ * `ERR_MODULE_NOT_FOUND` of Node.
+ *
+ * Only the package itself missing gets that message. A module that an installed `@markuplint/pretenders`
+ * needs being missing is a fault of the installation, and is thrown as it is (see `missingPackageOf` in
+ * `@markuplint/shared`).
+ *
+ * @param name - The export to load
+ * @param needs - What needs it, as the start of the sentence of the error: an option of the configuration
+ * @returns The export
+ * @throws An `Error` that says how to install the package, with the error of the import as its `cause`
+ */
+async function importFromPretenders(name, needs) {
+    try {
+        const mod = await import('@markuplint/pretenders');
+        return mod[name];
+    }
+    catch (error) {
+        if (isFatalError(error) || missingPackageOf(error) !== PRETENDERS_PACKAGE) {
+            throw error;
+        }
+        throw new Error(`${needs} needs ${PRETENDERS_PACKAGE}, which is not installed. Add it to your project as a development dependency (for example, npm install --save-dev ${PRETENDERS_PACKAGE}), together with the parser package of each language you scan: @markuplint/vue-parser for .vue, @markuplint/svelte-parser for .svelte, @markuplint/astro-parser for .astro (and @markuplint/jsx-parser, @markuplint/mdx-parser for JSX and MDX).`, { cause: error });
+    }
+}
+/**
+ * `Pretender.filePath` is written by scanners (and by hand, in `data`) relative to
+ * their own base directory, which is meaningless once entries from
+ * files/scan results/configurations scattered across different directories are
+ * merged into one flat list.
  * Rebasing to an absolute path immediately after each source is read is
  * what lets {@link disambiguatePretendersForFile} later compare a
  * pretender's origin file against the lint target's resolved imports.
@@ -20,7 +52,8 @@ function rebasePretenderFilePaths(pretenders, baseDir) {
  * kept as well — the host's next config resolution creates a new resolver).
  *
  * @param config - The pretenders configuration section from the optimized config
- * @returns The resolver; its `resolve()` yields `[]` when `config` is absent
+ * @returns The resolver; its `resolve()` yields `[]` when `config` is absent, and rejects as
+ *   {@link resolvePretenders} does when `@markuplint/pretenders` is needed and not installed
  */
 export function createPretenderResolver(config) {
     // The promise is retained, not its result, so that overlapping first calls
@@ -69,6 +102,10 @@ export function createPretenderResolver(config) {
  * @param context - The lint target's path/source, required only for `config.auto`
  * @param options - Where to report the files the result depends on
  * @returns An array of all resolved pretender definitions
+ * @throws An `Error` that says how to install `@markuplint/pretenders` when `config.scan` or
+ *   `config.auto` needs it and it is not installed (an optional peer of this package), with the
+ *   error of the import as its `cause`. A module that an installed `@markuplint/pretenders`
+ *   needs being missing is thrown as it is.
  */
 export function resolvePretenders(config, context, options) {
     return createPretenderResolver(config).resolve(context, options);
@@ -108,13 +145,21 @@ async function resolveTargetIndependentPretenders(config) {
         }
     }
     if (config.data) {
-        data.push(...config.data);
+        // A configuration file's `data` is already absolute (resolved by the config provider
+        // from the file's own directory). What is relative here comes from a configuration with
+        // no file behind it (`MLEngine`'s `config` / `defaultConfig` option), which has no
+        // directory of its own, so it is read from `process.cwd()` — as its `scan` globs are.
+        const cwd = process.cwd();
+        data.push(...config.data.map(pretender => rebaseHandWrittenPretenderFilePath(pretender, p => path.resolve(cwd, p))));
     }
     if (config.scan) {
-        const { scan } = await import('@markuplint/pretenders');
+        const scan = await importFromPretenders('scan', 'The "pretenders.scan" option');
         for (const entry of config.scan) {
             const patterns = typeof entry.files === 'string' ? [entry.files] : [...entry.files];
-            const globResults = await Promise.all(patterns.map(p => glob(p)));
+            // The patterns are absolute paths of the platform (`#pathResolve`), which Windows writes
+            // with backslashes, and a glob reads one as an escape unless it is a slash. Only there:
+            // elsewhere a backslash is the escape a pattern may mean (`\[id\]`, a directory of brackets).
+            const globResults = await Promise.all(patterns.map(p => glob(process.platform === 'win32' ? normalizeForGlob(p) : p)));
             const resolved = globResults.flat().map(f => path.resolve(f));
             if (resolved.length > 0) {
                 const scanned = await scan(resolved, {
@@ -133,7 +178,7 @@ async function resolveTargetIndependentPretenders(config) {
  * `context`'s import graph to `data`, the target-independent entries.
  */
 async function appendAutoPretenders(data, context, auto, dependencies) {
-    const { autoScan } = await import('@markuplint/pretenders');
+    const autoScan = await importFromPretenders('autoScan', 'The "pretenders.auto" option');
     const scanned = await autoScan(context.filePath, context.sourceCode, {
         depth: auto === true ? undefined : auto.depth,
         dependencies,
@@ -179,12 +224,14 @@ async function appendAutoPretenders(data, context, auto, dependencies) {
  * @param options - Where to report the files the result depends on
  * @returns The disambiguated pretender list, or `pretenders` itself (same
  *   reference) when there was nothing to resolve
+ * @throws An `Error` that says how to install `@markuplint/pretenders` when an entry has a
+ *   `filePath` and it is not installed, with the error of the import as its `cause`
  */
 export async function disambiguatePretendersForFile(filePath, sourceCode, pretenders, options) {
     if (!pretenders.some(pretender => pretender.filePath)) {
         return pretenders;
     }
-    const { disambiguatePretenders } = await import('@markuplint/pretenders');
+    const disambiguatePretenders = await importFromPretenders('disambiguatePretenders', 'A pretender that has a `filePath`');
     // The same base the scanned pretenders' paths were made absolute from (see `rebasePretenderFilePaths`).
     return disambiguatePretenders(pretenders, {
         filePath,
@@ -223,11 +270,24 @@ export function hasResolvableCollision(pretenders) {
  * 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.
+ * caches in that case either, and when it is installed but fails to load, which
+ * is logged under the `ml-fr` debug namespace: what needs it fails on its own, with the reason.
  *
  * @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();
+    let clearPretenderCaches;
+    try {
+        ({ clearPretenderCaches } = await import('@markuplint/pretenders'));
+    }
+    catch (error) {
+        // Clearing is best-effort, and what needs the package fails on its own with the reason when it is
+        // loaded, so a package that fails to load is logged and left to that. Tier-1-shaped errors are not
+        // told apart here either: a module the package needs runs as it loads, as in `generalImport`.
+        if (missingPackageOf(error) !== PRETENDERS_PACKAGE) {
+            log('Failed to load %s to clear its caches: %O', PRETENDERS_PACKAGE, error);
+        }
+        return;
+    }
+    clearPretenderCaches();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/file-resolver",
-	"version": "5.3.0",
+	"version": "5.5.0",
 	"description": "The file resolver of markuplint",
 	"repository": {
 		"type": "git",
@@ -31,25 +31,33 @@
 		"clean": "tsc --build --clean"
 	},
 	"devDependencies": {
+		"@markuplint/pretenders": "5.5.0",
 		"@types/node": "24.19.2"
 	},
+	"peerDependencies": {
+		"@markuplint/pretenders": "^5.4.0"
+	},
+	"peerDependenciesMeta": {
+		"@markuplint/pretenders": {
+			"optional": true
+		}
+	},
 	"dependencies": {
-		"@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",
+		"@markuplint/html-parser": "5.5.0",
+		"@markuplint/ml-ast": "5.5.0",
+		"@markuplint/ml-config": "5.5.0",
+		"@markuplint/ml-core": "5.5.0",
+		"@markuplint/ml-spec": "5.5.0",
+		"@markuplint/parser-utils": "5.5.0",
+		"@markuplint/selector": "5.5.0",
+		"@markuplint/shared": "5.5.0",
 		"cosmiconfig": "^10.0.1",
 		"debug": "^4.4.3",
-		"glob": "^13.0.6",
-		"ignore": "^7.0.12",
+		"glob": "^14.0.3",
+		"ignore": "^7.0.14",
 		"import-meta-resolve": "^4.2.0",
 		"jsonc": "^3.0.0",
-		"minimatch": "^10.2.6"
+		"minimatch": "^11.0.4"
 	},
-	"gitHead": "f587cf0206c8426e57369a48d6d5fb22306eafde"
+	"gitHead": "fedebcfd56eaec4642e68643b2f9e10750d810e1"
 }