@markuplint/file-resolver 5.0.1 → 5.1.0

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.1.0](https://github.com/markuplint/markuplint/compare/v5.0.1...v5.1.0) (2026-10-08)
+
+### Features
+
+- **file-resolver:** add createPretenderResolver for one lint target across edits ([e8e2e55](https://github.com/markuplint/markuplint/commit/e8e2e55c523d38e0bacf54a8229bba6c1b91d6e4)), closes [#4064](https://github.com/markuplint/markuplint/issues/4064)
+- **file-resolver:** pass `pretenders.auto.depth` on to `autoScan` ([dad6334](https://github.com/markuplint/markuplint/commit/dad63348db7336b47b0287246dd29a36de97ee3a)), closes [#4066](https://github.com/markuplint/markuplint/issues/4066)
+- **file-resolver:** report the files a pretenders resolution depends on ([9257322](https://github.com/markuplint/markuplint/commit/92573229d0493387380adab6c7ecba1b902a2869)), closes [#4065](https://github.com/markuplint/markuplint/issues/4065)
+
 ## [5.0.1](https://github.com/markuplint/markuplint/compare/v5.0.0...v5.0.1) (2026-09-22)
 
 **Note:** Version bump only for package @markuplint/file-resolver

package/lib/path-utils.d.ts

@@ -16,7 +16,7 @@ export declare function fromFileURL(fileUrl: string): string;
  * 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()` —
+ * Mirrors `packages/@markuplint/language-server/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

package/lib/path-utils.js

@@ -22,7 +22,7 @@ export function fromFileURL(fileUrl) {
  * 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()` —
+ * Mirrors `packages/@markuplint/language-server/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

package/lib/resolve-pretenders.d.ts

@@ -11,6 +11,68 @@ export type ResolvePretendersContext = {
     /** Full source text of the file being linted (may be unsaved editor content) */
     readonly sourceCode: string;
 };
+/**
+ * Where a resolution reports what it read.
+ */
+export type ResolvePretendersOptions = {
+    /**
+     * A sink the resolution adds to: the normalized (`/`-delimited) absolute
+     * paths of the files whose content its result depends on, which a
+     * watch-mode host watches to learn when to resolve again (#4065). It covers
+     * what `config.scan` and `config.auto` read, and — for
+     * {@link disambiguatePretendersForFile} — the `tsconfig.json` the target's
+     * imports were resolved with. The lint target itself is not excluded; the
+     * caller already holds it.
+     *
+     * Not covered, because a change to them is not picked up even by resolving
+     * again: `config.files` and `config.imports` (`generalImport` keeps what it
+     * loaded for the life of the process). For what else is out of reach, see
+     * `PretenderScanOptions#dependencies` in `@markuplint/ml-config`.
+     */
+    readonly dependencies?: Set<string>;
+};
+/**
+ * Resolves pretenders for one lint target, across edits of that target.
+ *
+ * The sections of `config.pretenders` split by what their result depends on.
+ * `files`, `imports`, `data`, and `scan` depend on the config and the
+ * filesystem only; `auto` depends on the target's own source as well — the
+ * import graph it walks starts from the target's import statements. (So does
+ * the selector disambiguation the caller runs on the result.) A resolver
+ * reads the first group once, on the first `resolve()`, and reads the target
+ * on every `resolve()`, so a host that re-resolves after each edit of the
+ * target (`MLEngine.setCode`) re-does exactly the part an edit can change.
+ * The first group is read again only by a new resolver, which a host creates
+ * on each config resolution — a change on disk to a scanned component is
+ * therefore picked up with the next config resolution, not with the next
+ * edit of the target. See #4064.
+ *
+ * A watch-mode host closes that gap by watching the files `resolve()` reports
+ * in {@link ResolvePretendersOptions.dependencies}: a change to one of them
+ * makes it resolve the config again, which creates the new resolver. See #4065.
+ */
+export type PretenderResolver = {
+    /**
+     * @param context - The lint target's path/source, required only for
+     *   `config.auto`; without it `auto` is skipped, as in {@link resolvePretenders}
+     * @param options - Where to report the files the result depends on. The
+     *   retained target-independent entries report theirs on every call, not
+     *   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
+     */
+    resolve(context?: ResolvePretendersContext, options?: ResolvePretendersOptions): Promise<Pretender[]>;
+};
+/**
+ * Creates a {@link PretenderResolver} for `config`. One resolver stands for one
+ * resolution of the config: its target-independent entries are read on the
+ * first `resolve()` and kept for the resolver's lifetime (a failure there is
+ * 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
+ */
+export declare function createPretenderResolver(config: PretendersConfig): PretenderResolver;
 /**
  * Resolves pretender definitions from files, imported modules, inline data,
  * dynamic component scanning, and (when `context` is given) the lint
@@ -24,14 +86,20 @@ export type ResolvePretendersContext = {
  * 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
+ * 5. `config.auto` — on-demand scan of `context`'s own import graph, up to
+ *    `config.auto.depth` hops when the object form gives one (requires
  *    `context`; a no-op without it, e.g. when the caller has no lint target yet)
  *
+ * Equivalent to one `resolve()` of a fresh {@link createPretenderResolver};
+ * a host that resolves the same config repeatedly for one target keeps the
+ * resolver instead.
+ *
  * @param config - The pretenders configuration section from the optimized 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
  */
-export declare function resolvePretenders(config: PretendersConfig, context?: ResolvePretendersContext): Promise<Pretender[]>;
+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`
@@ -42,10 +110,11 @@ export declare function resolvePretenders(config: PretendersConfig, context?: Re
  * @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
  */
-export declare function disambiguatePretendersForFile(filePath: string, sourceCode: string, pretenders: readonly Pretender[]): Promise<readonly Pretender[]>;
+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`

package/lib/resolve-pretenders.js

@@ -13,6 +13,37 @@ import { generalImport } from './general-import.js';
 function rebasePretenderFilePaths(pretenders, baseDir) {
     return pretenders.map(pretender => rebasePretenderFilePath(pretender, relPath => path.resolve(baseDir, relPath)));
 }
+/**
+ * Creates a {@link PretenderResolver} for `config`. One resolver stands for one
+ * resolution of the config: its target-independent entries are read on the
+ * first `resolve()` and kept for the resolver's lifetime (a failure there is
+ * 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
+ */
+export function createPretenderResolver(config) {
+    // The promise is retained, not its result, so that overlapping first calls
+    // share one read, and the files it was read from ride along with the result.
+    let targetIndependent = null;
+    return {
+        async resolve(context, options) {
+            if (!config) {
+                return [];
+            }
+            targetIndependent ??= resolveTargetIndependentPretenders(config);
+            const retained = await targetIndependent;
+            const data = [...retained.pretenders];
+            for (const dependency of retained.dependencies) {
+                options?.dependencies?.add(dependency);
+            }
+            if (config.auto && context) {
+                await appendAutoPretenders(data, context, config.auto, options?.dependencies);
+            }
+            return data;
+        },
+    };
+}
 /**
  * Resolves pretender definitions from files, imported modules, inline data,
  * dynamic component scanning, and (when `context` is given) the lint
@@ -26,18 +57,29 @@ function rebasePretenderFilePaths(pretenders, baseDir) {
  * 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
+ * 5. `config.auto` — on-demand scan of `context`'s own import graph, up to
+ *    `config.auto.depth` hops when the object form gives one (requires
  *    `context`; a no-op without it, e.g. when the caller has no lint target yet)
  *
+ * Equivalent to one `resolve()` of a fresh {@link createPretenderResolver};
+ * a host that resolves the same config repeatedly for one target keeps the
+ * resolver instead.
+ *
  * @param config - The pretenders configuration section from the optimized 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
  */
-export async function resolvePretenders(config, context) {
-    if (!config) {
-        return [];
-    }
+export function resolvePretenders(config, context, options) {
+    return createPretenderResolver(config).resolve(context, options);
+}
+/**
+ * Steps 1–4 of {@link resolvePretenders}: the sections whose result does not
+ * depend on the lint target.
+ */
+async function resolveTargetIndependentPretenders(config) {
     const data = [];
+    const dependencies = new Set();
     if (config.files) {
         for (const file of config.files) {
             const pretenderFile = await generalImport(file);
@@ -77,41 +119,49 @@ export async function resolvePretenders(config, context) {
             if (resolved.length > 0) {
                 const scanned = await scan(resolved, {
                     ignoreComponentNames: entry.ignoreComponentNames ? [...entry.ignoreComponentNames] : undefined,
+                    dependencies,
                 });
                 // `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);
+    return { pretenders: data, dependencies };
+}
+/**
+ * Step 5 of {@link resolvePretenders}: appends what `config.auto` finds in
+ * `context`'s import graph to `data`, the target-independent entries.
+ */
+async function appendAutoPretenders(data, context, auto, dependencies) {
+    const { autoScan } = await import('@markuplint/pretenders');
+    const scanned = await autoScan(context.filePath, context.sourceCode, {
+        depth: auto === true ? undefined : auto.depth,
+        dependencies,
+    });
+    // `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;
             }
-            data.push(pretender);
+            seen.add(key);
         }
+        data.push(pretender);
     }
-    return data;
 }
 /**
  * Resolves selector collisions in `pretenders` for the specific file about
@@ -123,15 +173,16 @@ export async function resolvePretenders(config, context) {
  * @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
  */
-export async function disambiguatePretendersForFile(filePath, sourceCode, pretenders) {
+export async function disambiguatePretendersForFile(filePath, sourceCode, pretenders, options) {
     if (!hasResolvableCollision(pretenders)) {
         return pretenders;
     }
     const { disambiguatePretenders } = await import('@markuplint/pretenders');
-    return disambiguatePretenders(pretenders, { filePath, sourceCode });
+    return disambiguatePretenders(pretenders, { filePath, sourceCode, dependencies: options?.dependencies });
 }
 /**
  * Deliberately gates on selector+filePath duplication alone — NOT on the

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/file-resolver",
-	"version": "5.0.1",
+	"version": "5.1.0",
 	"description": "The file resolver of markuplint",
 	"repository": {
 		"type": "git",
@@ -34,15 +34,15 @@
 		"@types/node": "24.13.3"
 	},
 	"dependencies": {
-		"@markuplint/html-parser": "5.0.1",
-		"@markuplint/ml-ast": "5.0.1",
-		"@markuplint/ml-config": "5.0.1",
-		"@markuplint/ml-core": "5.0.1",
-		"@markuplint/ml-spec": "5.0.1",
-		"@markuplint/parser-utils": "5.0.1",
-		"@markuplint/pretenders": "5.0.1",
-		"@markuplint/selector": "5.0.1",
-		"@markuplint/shared": "5.0.1",
+		"@markuplint/html-parser": "5.1.0",
+		"@markuplint/ml-ast": "5.1.0",
+		"@markuplint/ml-config": "5.1.0",
+		"@markuplint/ml-core": "5.1.0",
+		"@markuplint/ml-spec": "5.1.0",
+		"@markuplint/parser-utils": "5.1.0",
+		"@markuplint/pretenders": "5.1.0",
+		"@markuplint/selector": "5.1.0",
+		"@markuplint/shared": "5.1.0",
 		"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": "edbaeedca5588fb291ea9d4e21a4ab2bf41fc9cb"
+	"gitHead": "3a061784a8211034ad0c1cbd64798c0213414f65"
 }