markuplint 5.0.1 → 5.1.0

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 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)
+
+### Bug Fixes
+
+- **markuplint:** poll for file changes under Deno ([ccfeea1](https://github.com/markuplint/markuplint/commit/ccfeea1e1726fda526deff979cafac5093f179bb))
+- **markuplint:** re-resolve the pretenders that depend on the source on setCode ([525404e](https://github.com/markuplint/markuplint/commit/525404e296b1936ef86e48d03f79479071c7e7d0)), closes [#4064](https://github.com/markuplint/markuplint/issues/4064)
+- **ml-spec:** read option, SVG title and control text through the accname resolver ([4c66d1f](https://github.com/markuplint/markuplint/commit/4c66d1fb960e746dc9f3c6cec0c8b3c9284a657e))
+- **ml-spec:** read the SVG title and select options through the accname resolver ([0a7c162](https://github.com/markuplint/markuplint/commit/0a7c162a83a553d7872388184ea0020735def6fb)), closes [#4067](https://github.com/markuplint/markuplint/issues/4067)
+- **pretenders:** compose slots and contents through a chain of components ([ac6147f](https://github.com/markuplint/markuplint/commit/ac6147f4caee1a61d40c7925321fb0cdb64a88b8)), closes [#4057](https://github.com/markuplint/markuplint/issues/4057)
+
+### Features
+
+- **language-server:** add a language server that runs on any LSP client ([ab03edc](https://github.com/markuplint/markuplint/commit/ab03edc35457b6502a9d55e176a8adca5427f796))
+- **markuplint:** watch the files that pretenders.scan and auto read ([b4c63ef](https://github.com/markuplint/markuplint/commit/b4c63ef246cb42ecd1b943de46dca1f58738a701)), closes [#4065](https://github.com/markuplint/markuplint/issues/4065)
+
+### Performance Improvements
+
+- **markuplint:** retain parsed documents only when suppressions scope needs them ([1f5326a](https://github.com/markuplint/markuplint/commit/1f5326a14d8efbf1da441452b192bcfcd3892384))
+
 ## [5.0.1](https://github.com/markuplint/markuplint/compare/v5.0.0...v5.0.1) (2026-09-22)
 
 ### Bug Fixes

package/lib/api/ml-engine.d.ts

@@ -88,7 +88,8 @@ export declare class MLEngine extends Emitter<MLEngineEventMap> {
      */
     get document(): Document<RuleConfigValue, PlainData> | null;
     /**
-     * Closes the engine, removing all event listeners and stopping the file watcher.
+     * Closes the engine, removing all event listeners and leaving the file
+     * watcher (the files no other engine watches are released with it).
      */
     close(): Promise<void>;
     /**
@@ -96,18 +97,49 @@ export declare class MLEngine extends Emitter<MLEngineEventMap> {
      *
      * Sets up the engine on first call, then verifies the document against all rules.
      *
+     * Runs after whatever the engine is already doing — an earlier `exec()`, a
+     * {@link setCode} call, a re-resolution a watched file triggered — and
+     * before whatever is asked for later. That also means that awaiting it from
+     * inside one of the engine's own event listeners waits on itself.
+     *
      * @returns The lint result including violations and fixed code, or `null` if setup was skipped
      */
     exec(): Promise<MLResultInfo | null>;
     /**
-     * Updates the source code and re-parses the document without re-resolving configuration.
+     * Updates the source code and re-parses the document without re-resolving
+     * configuration.
+     *
+     * The pretenders that depend on the source — `pretenders.auto`, which walks
+     * the file's own imports, and the disambiguation of same-selector entries,
+     * which reads them too — are re-resolved from the new code; the ones that
+     * depend on the config and the filesystem only are kept from the latest
+     * config resolution (see #4064 and {@link PretenderResolver}).
+     *
+     * When calls overlap, only the latest one takes effect, and every call
+     * settles only once that latest one has — so a host that runs
+     * {@link exec} right after awaiting any of them (the VS Code extension
+     * does) lints the document the file now holds, never the previous
+     * document against the newer file. For the same reason a superseded call
+     * rejects when the latest one fails: resolving would tell its caller the
+     * latest code is in place when it is not.
      *
      * @param code - The new markup source code
      */
     setCode(code: string): Promise<void>;
     /**
-     * Enables or disables watch mode. When enabled, the engine watches config files
-     * for changes and re-lints automatically.
+     * Enables or disables watch mode. When enabled, the engine watches the
+     * files its result depends on — config files, and the component files
+     * `pretenders.scan` and `pretenders.auto` read — and re-lints automatically
+     * when one changes, is created, or is removed. Changes that arrive together
+     * are one re-lint, and the lint target itself is not watched: it may be
+     * watched and managed by a language server or text editor, which tells the
+     * engine through {@link setCode}.
+     *
+     * Not watched, so a change to them is picked up only by the next
+     * config-triggered re-lint: files that do not exist yet (a component that
+     * has not been created, a `scan` glob's new match), `node_modules`,
+     * `pretenders.files` and `pretenders.imports`. See
+     * `PretenderScanOptions#dependencies` in `@markuplint/ml-config`.
      *
      * @param enable - Whether to enable watch mode
      */

package/lib/api/ml-engine.js

@@ -1,12 +1,13 @@
-import { ConfigProvider, disambiguatePretendersForFile, invalidatePretenderResolutionCaches, resolveFiles, resolveParser, resolvePretenders, resolveRules, resolveSpecs, } from '@markuplint/file-resolver';
+import { ConfigProvider, createPretenderResolver, disambiguatePretendersForFile, invalidatePretenderResolutionCaches, resolveFiles, resolveParser, resolveRules, resolveSpecs, } from '@markuplint/file-resolver';
+import path from 'node:path';
 import { applyRuleAliasesToConfig, mergeConfig } from '@markuplint/ml-config';
 import { MLCore, convertRuleset } from '@markuplint/ml-core';
 import { ruleAliasTable } from '@markuplint/rules';
 import { isFatalError } from '@markuplint/shared';
-import { FSWatcher } from 'chokidar';
 import { Emitter } from 'strict-event-emitter';
 import { log as coreLog, verbosely } from '../debug.js';
 import { i18n } from '../i18n.js';
+import { subscribe as subscribeToWatcher, toWatchKey } from './shared-watcher.js';
 const log = coreLog.extend('ml-engine');
 const fileLog = log.extend('file');
 const configLog = log.extend('config');
@@ -19,6 +20,15 @@ const configLog = log.extend('config');
  * way a stable `options.config`/`defaultConfig` reference does. See #3997.
  */
 const RECOMMENDED_CONFIG = { extends: ['markuplint:recommended'] };
+/**
+ * How long watch events are gathered before the engine re-resolves, so that
+ * a change of many files at once (a `git checkout`, a formatter run) is one
+ * re-resolution. Rollup's `watch.buildDelay` is 25ms; tsc waits 250ms and
+ * webpack 20ms. A re-resolution is not interrupted by events that arrive
+ * during it (see `#watchRerun`), so the delay only has to be long enough to
+ * gather the burst, not to outlast the work.
+ */
+const WATCH_DEBOUNCE_MS = 25;
 /**
  * The main markuplint engine that orchestrates file resolution, configuration loading,
  * parsing, and linting. Supports both single-file and watch-mode operation.
@@ -64,7 +74,53 @@ export class MLEngine extends Emitter {
     #core = null;
     #file;
     #options;
-    #watcher = new FSWatcher();
+    /**
+     * The resolver of the latest config resolution, kept so `setCode()` can
+     * re-resolve the pretenders that depend on the source without re-reading
+     * the ones that depend on the config and the filesystem only. See #4064.
+     */
+    #pretenderResolver = null;
+    /**
+     * Counts `setCode()` calls so that, when they overlap, only the latest one
+     * reaches the file and the core — `setCode()` awaits the pretender
+     * re-resolution, and an earlier call finishing later must not put its
+     * older code back.
+     */
+    #setCodeSeq = 0;
+    /**
+     * The latest `setCode()` call's application, so that a superseded call can
+     * resolve only after it has taken effect.
+     */
+    #latestSetCode = Promise.resolve();
+    /**
+     * What is running, so that the next piece of work starts when it is over:
+     * {@link exec}, the application of {@link setCode}, and the re-resolution a
+     * watched file triggers share one queue. They all read and replace the same
+     * state — the pretender resolver, the core's document — and `verify()` with
+     * `fix` rewrites the document while it runs; run side by side, a lint could
+     * see another's half-done state, and the one that finished last would put
+     * its older pretenders over a newer resolution.
+     */
+    #queue = Promise.resolve();
+    /**
+     * This engine's view of the process-wide watcher (see `./shared-watcher.ts`);
+     * `null` unless watching.
+     */
+    #watch = null;
+    /** The config files of the latest resolution, as {@link ConfigSet.files} names them. */
+    #configFiles = new Set();
+    /**
+     * The files the latest pretenders resolution read (see
+     * `ResolvePretendersOptions#dependencies`). `setCode()` replaces them, as
+     * the `auto` ones follow the source's imports.
+     */
+    #pretenderDependencies = new Set();
+    /** The pending gathering of watch events into one re-resolution. */
+    #watchDebounce;
+    /** Whether the loop of re-resolutions is running, one at a time. */
+    #rerunning = false;
+    /** Set by an event that arrives while a re-resolution is running: it ran on state older than the event. */
+    #rerunAgain = false;
     constructor(file, options) {
         super();
         if (this.#options?.debug) {
@@ -86,20 +142,29 @@ export class MLEngine extends Emitter {
         return this.#core?.document ?? null;
     }
     /**
-     * Closes the engine, removing all event listeners and stopping the file watcher.
+     * Closes the engine, removing all event listeners and leaving the file
+     * watcher (the files no other engine watches are released with it).
      */
     async close() {
         this.removeAllListeners();
-        await this.#watcher.close();
+        await this.#stopWatching();
     }
     /**
      * Executes linting on the target file and returns the results.
      *
      * Sets up the engine on first call, then verifies the document against all rules.
      *
+     * Runs after whatever the engine is already doing — an earlier `exec()`, a
+     * {@link setCode} call, a re-resolution a watched file triggered — and
+     * before whatever is asked for later. That also means that awaiting it from
+     * inside one of the engine's own event listeners waits on itself.
+     *
      * @returns The lint result including violations and fixed code, or `null` if setup was skipped
      */
-    async exec() {
+    exec() {
+        return this.#enqueue(() => this.#exec());
+    }
+    async #exec() {
         log('exec: start');
         const core = await this.#setup();
         if (!core) {
@@ -160,21 +225,71 @@ export class MLEngine extends Emitter {
         };
     }
     /**
-     * Updates the source code and re-parses the document without re-resolving configuration.
+     * Updates the source code and re-parses the document without re-resolving
+     * configuration.
+     *
+     * The pretenders that depend on the source — `pretenders.auto`, which walks
+     * the file's own imports, and the disambiguation of same-selector entries,
+     * which reads them too — are re-resolved from the new code; the ones that
+     * depend on the config and the filesystem only are kept from the latest
+     * config resolution (see #4064 and {@link PretenderResolver}).
+     *
+     * When calls overlap, only the latest one takes effect, and every call
+     * settles only once that latest one has — so a host that runs
+     * {@link exec} right after awaiting any of them (the VS Code extension
+     * does) lints the document the file now holds, never the previous
+     * document against the newer file. For the same reason a superseded call
+     * rejects when the latest one fails: resolving would tell its caller the
+     * latest code is in place when it is not.
      *
      * @param code - The new markup source code
      */
     async setCode(code) {
+        // Numbered when called, not when its turn in the queue comes: a call that
+        // a later one has overtaken by then steps aside without resolving anything.
+        const seq = ++this.#setCodeSeq;
+        const applied = this.#enqueue(() => this.#applyCode(code, seq));
+        this.#latestSetCode = applied;
+        await applied;
+        let awaited = applied;
+        while (this.#latestSetCode !== awaited) {
+            awaited = this.#latestSetCode;
+            await awaited;
+        }
+    }
+    /**
+     * The body of one {@link setCode} call. Two checks against the sequence
+     * number: the one after setup spares a superseded call its resolution;
+     * the one after resolution keeps a superseded call that was already
+     * resolving from overwriting the newer result.
+     */
+    async #applyCode(code, seq) {
         const core = await this.#setup();
-        if (!core) {
+        if (!core || seq !== this.#setCodeSeq) {
             return;
         }
         this.#file.setCode(code);
-        core.setCode(code);
+        const { pretenders, dependencies } = await this.#resolvePretendersForCurrentCode();
+        if (seq !== this.#setCodeSeq) {
+            return;
+        }
+        core.setCode(code, { pretenders });
+        await this.#watchPretenderDependencies(dependencies);
     }
     /**
-     * Enables or disables watch mode. When enabled, the engine watches config files
-     * for changes and re-lints automatically.
+     * Enables or disables watch mode. When enabled, the engine watches the
+     * files its result depends on — config files, and the component files
+     * `pretenders.scan` and `pretenders.auto` read — and re-lints automatically
+     * when one changes, is created, or is removed. Changes that arrive together
+     * are one re-lint, and the lint target itself is not watched: it may be
+     * watched and managed by a language server or text editor, which tells the
+     * engine through {@link setCode}.
+     *
+     * Not watched, so a change to them is picked up only by the next
+     * config-triggered re-lint: files that do not exist yet (a component that
+     * has not been created, a `scan` glob's new match), `node_modules`,
+     * `pretenders.files` and `pretenders.imports`. See
+     * `PretenderScanOptions#dependencies` in `@markuplint/ml-config`.
      *
      * @param enable - Whether to enable watch mode
      */
@@ -184,12 +299,24 @@ export class MLEngine extends Emitter {
             watch: enable,
         };
         if (enable) {
-            this.#watcher.on('change', this.#onChange.bind(this));
+            if (!this.#watch) {
+                this.#watch = subscribeToWatcher(filePath => this.#watchOnChange(filePath), error => this.#emitWatchError(error));
+                // Whatever the engine already depends on; it resolves the rest as it goes.
+                void this.#syncWatch();
+            }
         }
         else {
-            this.#watcher.removeAllListeners();
+            this.#stopWatching().catch((error) => {
+                if (isFatalError(error)) {
+                    throw error;
+                }
+                this.#emitWatchError(error);
+            });
         }
     }
+    #emitWatchError(error) {
+        this.emit('log', 'watch:error', error instanceof Error ? error.message : String(error));
+    }
     async #createCore(fabric) {
         fileLog('Get source code');
         const sourceCode = await this.#file.getCode();
@@ -206,13 +333,68 @@ export class MLEngine extends Emitter {
         this.#core = core;
         return core;
     }
-    async #onChange(filePath) {
+    /**
+     * A watched file changed, was created, or was removed. Gathers the events
+     * of a burst, then asks for a re-resolution.
+     */
+    #watchOnChange(filePath) {
         if (!this.#options?.watch) {
             return;
         }
         this.emit('log', 'watch:onChange', filePath);
+        clearTimeout(this.#watchDebounce);
+        this.#watchDebounce = setTimeout(() => {
+            this.#watchDebounce = undefined;
+            void this.#watchRerun();
+        }, WATCH_DEBOUNCE_MS);
+    }
+    /**
+     * Re-resolves and lints, one at a time. An event that arrives while one is
+     * running means it ran on state older than the event, so it is followed by
+     * exactly one more — however many events came — rather than by one each,
+     * and never alongside it (the same way Rollup's watcher reruns, and webpack
+     * discards a compilation that a change has outdated).
+     */
+    async #watchRerun() {
+        if (this.#rerunning) {
+            this.#rerunAgain = true;
+            return;
+        }
+        this.#rerunning = true;
+        try {
+            do {
+                this.#rerunAgain = false;
+                try {
+                    await this.#enqueue(() => this.#resolveAgain());
+                }
+                catch (error) {
+                    if (isFatalError(error)) {
+                        throw error;
+                    }
+                    // Nobody awaits a re-resolution a file triggered; a failure of one (a
+                    // parser that cannot be found, say) must not become an unhandled
+                    // rejection, nor spare the event that arrived while it ran its rerun.
+                    this.#emitWatchError(error);
+                }
+            } while (this.#rerunAgain && this.#options?.watch);
+        }
+        finally {
+            this.#rerunning = false;
+            if (!this.#watchDebounce) {
+                this.emit('log', 'watch:idle', this.#file.path);
+            }
+        }
+    }
+    /**
+     * A re-resolution is not only the config: it re-reads the files the pretenders
+     * depend on, which is what a change to one of them is for.
+     */
+    async #resolveAgain() {
+        if (!this.#options?.watch) {
+            return;
+        }
         const fabric = await this.#provide(false);
-        if (!fabric) {
+        if (!fabric || !this.#options?.watch) {
             return;
         }
         if (fabric.configErrors) {
@@ -220,7 +402,67 @@ export class MLEngine extends Emitter {
         }
         this.emit('log', 'update:core', this.#file.path);
         this.#core?.update(fabric);
-        await this.exec();
+        await this.#exec();
+    }
+    #enqueue(task) {
+        const result = this.#queue.then(task, task);
+        // The queue goes on whether this task succeeded or not; its failure is the
+        // caller's, through `result`.
+        this.#queue = result.then(() => { }, () => { });
+        return result;
+    }
+    /**
+     * Leaves the process-wide watcher. A later `watchMode(true)` subscribes anew.
+     */
+    async #stopWatching() {
+        clearTimeout(this.#watchDebounce);
+        this.#watchDebounce = undefined;
+        this.#options = { ...this.#options, watch: false };
+        const watch = this.#watch;
+        this.#watch = null;
+        await watch?.close();
+    }
+    /**
+     * Points the process-wide watcher at what this engine depends on now: its
+     * config files and the files its pretenders were resolved from. Resolves
+     * once they are being watched, so that a change made after an `exec()` or
+     * `setCode()` has resolved is not missed.
+     *
+     * Left out: relative names (`markuplint:recommended`, the keys of inline
+     * configs, `extends` of an npm module) that {@link ConfigSet.files} also
+     * lists, and the lint target itself.
+     *
+     * Never rejects: a watcher that cannot be updated costs the engine its
+     * re-linting, not the `exec()` / `setCode()` whose result is already in hand.
+     */
+    async #syncWatch() {
+        try {
+            await this.#updateWatch();
+        }
+        catch (error) {
+            if (isFatalError(error)) {
+                throw error;
+            }
+            this.#emitWatchError(error);
+        }
+    }
+    async #updateWatch() {
+        const watch = this.#watch;
+        if (!watch) {
+            return;
+        }
+        const targetKey = toWatchKey(this.#file.path);
+        const filePaths = new Set();
+        for (const filePath of [...this.#configFiles, ...this.#pretenderDependencies]) {
+            if (path.isAbsolute(filePath) && toWatchKey(filePath) !== targetKey) {
+                filePaths.add(filePath);
+            }
+        }
+        await watch.update(filePaths);
+    }
+    async #watchPretenderDependencies(dependencies) {
+        this.#pretenderDependencies = dependencies;
+        await this.#syncWatch();
     }
     async #provide(cache = true) {
         let configSet;
@@ -380,10 +622,10 @@ export class MLEngine extends Emitter {
             ? { ...resolvedConfigSet, ruleDeprecations: [] }
             : { ...resolvedConfigSet, config: aliasedConfig, ruleDeprecations: ruleAliasWarnings };
         this.emit('config', this.#file.path, configSet);
-        if (this.#options?.watch) {
-            // It doesn't watch the main HTML file because it may is watched and managed by a language server or text editor or more.
-            this.#watcher.add([...configSet.files]);
-        }
+        // The main file is not watched (see `#syncWatch`): it may be watched and managed
+        // by a language server or text editor or more.
+        this.#configFiles = configSet.files;
+        await this.#syncWatch();
         return configSet;
     }
     async #resolveParser(
@@ -404,14 +646,35 @@ export class MLEngine extends Emitter {
             // resolving as it did before the change for the rest of the process's lifetime.
             await invalidatePretenderResolutionCaches();
         }
+        // One resolver per config resolution: this is the only place the
+        // pretenders that depend on the config and the filesystem (files /
+        // imports / data / scan) are read. `setCode()` reuses it.
+        this.#pretenderResolver = createPretenderResolver(configSet.config.pretenders);
+        const { pretenders, dependencies } = await this.#resolvePretendersForCurrentCode();
+        await this.#watchPretenderDependencies(dependencies);
+        return pretenders;
+    }
+    /**
+     * Disambiguation runs here, on every call, and not only at config
+     * resolution: it reads the target's import statements, so it is as
+     * source-dependent as `auto` is.
+     *
+     * @returns The pretenders, and the files they were resolved from, which the
+     *   caller watches once it has adopted this resolution (a superseded one is dropped).
+     */
+    async #resolvePretendersForCurrentCode() {
+        const resolver = this.#pretenderResolver;
+        const dependencies = new Set();
+        if (!resolver) {
+            return { pretenders: [], dependencies };
+        }
         const sourceCode = await this.#file.getCode();
-        const pretenders = await resolvePretenders(configSet.config.pretenders, {
-            filePath: this.#file.path,
-            sourceCode,
+        const pretenders = await resolver.resolve({ filePath: this.#file.path, sourceCode }, { dependencies });
+        const disambiguated = await disambiguatePretendersForFile(this.#file.path, sourceCode, pretenders, {
+            dependencies,
         });
-        const disambiguated = await disambiguatePretendersForFile(this.#file.path, sourceCode, pretenders);
         fileLog('Resolved pretenders: %O', disambiguated);
-        return disambiguated;
+        return { pretenders: disambiguated, dependencies };
     }
     async #resolveRules(plugins, ruleset) {
         const rules = await resolveRules(plugins, ruleset, this.#options?.importPresetRules ?? true);

package/lib/api/shared-watcher.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @module shared-watcher
+ *
+ * One file watcher for the whole process, which every watching `MLEngine`
+ * subscribes to for the files it depends on: its config files and, since #4065,
+ * the files `pretenders.scan` / `pretenders.auto` read.
+ *
+ * Why not one `FSWatcher` per engine: chokidar keeps the `fs.watch` handle of a
+ * path in a module-level map, so every watcher of a process that watches the
+ * same file shares it — and when an editor saves through a rename (the usual
+ * way), each watcher re-attaches to the new inode by closing its own closer and
+ * opening a new one, which finds the old shared handle still held by the other
+ * watchers and attaches to that. After the second such save nobody is told of
+ * anything any more. The VS Code server runs one engine per open document, and
+ * a component is shared by many documents, so that is the normal case here.
+ * With a single watcher per process the handle has a single owner.
+ *
+ * What follows from how chokidar behaves, and shapes the code below:
+ *
+ * - A watcher that has been `close()`d is not revived: its listeners are gone,
+ *   its `ready` is spent, and its ignore list stays. A subscriber arriving
+ *   after all others have left gets a new watcher (a "generation"), and events
+ *   of an old one are dropped.
+ * - Only file paths are `unwatch()`ed. Unwatching a directory ignores
+ *   everything under it until that directory is added again, and directories
+ *   are watched on this module's behalf (for a file that does not exist yet).
+ *   They are released with the generation.
+ * - `add()` returns before the path is being watched, and nothing signals
+ *   completion. `update()` waits for it, by watching `getWatched()`, so that a
+ *   caller who has awaited it can rely on the next change being seen.
+ * - After `unlink`, chokidar re-attaches by itself only while it watches a
+ *   single path. Here it watches many, so the path is added again.
+ * - A removal is reported as `unlink` only after chokidar's 100ms atomic-write
+ *   window has passed without the file coming back; a save through a temporary
+ *   file never shows as one.
+ * - `unwatch()` adds the path to chokidar's ignore list until the next
+ *   `add()` of it, and the list is only cleared with the generation.
+ */
+export type WatchEventName = 'add' | 'change' | 'unlink';
+export type WatchListener = (filePath: string, event: WatchEventName) => void;
+/**
+ * A subscriber's view of the shared watcher.
+ */
+export type WatchSubscription = {
+    /**
+     * Sets the files the subscriber is told about. Resolves once chokidar is
+     * watching all of them (or gives up waiting), so a change made after it
+     * resolves is seen. Does nothing once the subscription is closed.
+     *
+     * @param filePaths - Absolute paths; a file that does not exist yet is
+     *   watched for its creation. Relative paths resolve against the cwd.
+     */
+    update(filePaths: Iterable<string>): Promise<void>;
+    /**
+     * Leaves the watcher; the last one to leave closes it, and resolves once its
+     * handles are released.
+     */
+    close(): Promise<void>;
+};
+/**
+ * The key two spellings of one file share: absolute, and without case on
+ * Windows (VS Code reports `c:\…`, TypeScript's real path says `C:\…`).
+ * Only for telling files apart — chokidar is given the path as it came.
+ *
+ * @param filePath - A path
+ * @returns The path in its comparable form
+ */
+export declare function toWatchKey(filePath: string): string;
+/**
+ * @param listener - Called with the path as given to {@link WatchSubscription.update}
+ * @param onError - Called with the errors chokidar reports (a path it cannot
+ *   watch, such as when the OS watch limit is reached); fatal ones are thrown
+ * @returns The subscription, which watches nothing until `update()`
+ */
+export declare function subscribe(listener: WatchListener, onError?: (error: unknown) => void): WatchSubscription;
+/**
+ * Resolves once the shared watcher is watching `filePath` again — after an
+ * `unlink`, when it has been re-attached asynchronously.
+ *
+ * @param filePath - A path some subscriber gave to `update()`
+ */
+export declare function whenWatching(filePath: string): Promise<void>;

package/lib/api/shared-watcher.js

@@ -0,0 +1,237 @@
+/**
+ * @module shared-watcher
+ *
+ * One file watcher for the whole process, which every watching `MLEngine`
+ * subscribes to for the files it depends on: its config files and, since #4065,
+ * the files `pretenders.scan` / `pretenders.auto` read.
+ *
+ * Why not one `FSWatcher` per engine: chokidar keeps the `fs.watch` handle of a
+ * path in a module-level map, so every watcher of a process that watches the
+ * same file shares it — and when an editor saves through a rename (the usual
+ * way), each watcher re-attaches to the new inode by closing its own closer and
+ * opening a new one, which finds the old shared handle still held by the other
+ * watchers and attaches to that. After the second such save nobody is told of
+ * anything any more. The VS Code server runs one engine per open document, and
+ * a component is shared by many documents, so that is the normal case here.
+ * With a single watcher per process the handle has a single owner.
+ *
+ * What follows from how chokidar behaves, and shapes the code below:
+ *
+ * - A watcher that has been `close()`d is not revived: its listeners are gone,
+ *   its `ready` is spent, and its ignore list stays. A subscriber arriving
+ *   after all others have left gets a new watcher (a "generation"), and events
+ *   of an old one are dropped.
+ * - Only file paths are `unwatch()`ed. Unwatching a directory ignores
+ *   everything under it until that directory is added again, and directories
+ *   are watched on this module's behalf (for a file that does not exist yet).
+ *   They are released with the generation.
+ * - `add()` returns before the path is being watched, and nothing signals
+ *   completion. `update()` waits for it, by watching `getWatched()`, so that a
+ *   caller who has awaited it can rely on the next change being seen.
+ * - After `unlink`, chokidar re-attaches by itself only while it watches a
+ *   single path. Here it watches many, so the path is added again.
+ * - A removal is reported as `unlink` only after chokidar's 100ms atomic-write
+ *   window has passed without the file coming back; a save through a temporary
+ *   file never shows as one.
+ * - `unwatch()` adds the path to chokidar's ignore list until the next
+ *   `add()` of it, and the list is only cleared with the generation.
+ */
+import path from 'node:path';
+import { isFatalError } from '@markuplint/shared';
+import { FSWatcher } from 'chokidar';
+/**
+ * The longest `update()` waits for chokidar to start watching. A path that is
+ * not being watched by then (a failure chokidar reports as an `error`) is not
+ * waited for any more; the update still resolves.
+ */
+const ARM_TIMEOUT_MS = 2000;
+/**
+ * Deno implements `fs.watch` of a file with an inotify watch on its inode, and
+ * counts the watches of a path: when chokidar re-attaches to a file that an
+ * atomic save has replaced, by closing its watch and opening a new one on the
+ * same path at once, the new watch is believed to exist already and stays on
+ * the old inode, deaf to every save after the second (Deno documents the
+ * atomic save dropping its own watcher on Linux, at
+ * https://docs.deno.com/runtime/run/watch_mode/). Polling does not go through
+ * that watch. Unconfirmed against Deno's source; it is what the CI of the
+ * Deno job shows.
+ */
+const IS_DENO = 'deno' in process.versions;
+const DENO_POLL_INTERVAL_MS = 50;
+let current = null;
+/**
+ * The key two spellings of one file share: absolute, and without case on
+ * Windows (VS Code reports `c:\…`, TypeScript's real path says `C:\…`).
+ * Only for telling files apart — chokidar is given the path as it came.
+ *
+ * @param filePath - A path
+ * @returns The path in its comparable form
+ */
+export function toWatchKey(filePath) {
+    const resolved = path.resolve(filePath);
+    return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+}
+/**
+ * @param listener - Called with the path as given to {@link WatchSubscription.update}
+ * @param onError - Called with the errors chokidar reports (a path it cannot
+ *   watch, such as when the OS watch limit is reached); fatal ones are thrown
+ * @returns The subscription, which watches nothing until `update()`
+ */
+export function subscribe(listener, onError) {
+    current ??= createGeneration();
+    const generation = current;
+    const subscriber = { generation, listener, onError, keys: new Set(), closed: false };
+    generation.subscribers.add(subscriber);
+    return {
+        update: filePaths => update(subscriber, filePaths),
+        close: () => close(subscriber),
+    };
+}
+/**
+ * Resolves once the shared watcher is watching `filePath` again — after an
+ * `unlink`, when it has been re-attached asynchronously.
+ *
+ * @param filePath - A path some subscriber gave to `update()`
+ */
+export async function whenWatching(filePath) {
+    const generation = current;
+    const entry = generation?.entries.get(toWatchKey(filePath));
+    if (generation && entry) {
+        await untilWatched(generation, [entry]);
+    }
+}
+function createGeneration() {
+    const watcher = new FSWatcher({
+        ignoreInitial: true,
+        ...(IS_DENO ? { usePolling: true, interval: DENO_POLL_INTERVAL_MS } : {}),
+    });
+    const generation = { watcher, entries: new Map(), subscribers: new Set() };
+    watcher.on('add', filePath => dispatch(generation, 'add', filePath));
+    watcher.on('change', filePath => dispatch(generation, 'change', filePath));
+    watcher.on('unlink', filePath => dispatch(generation, 'unlink', filePath));
+    watcher.on('error', error => {
+        if (isFatalError(error)) {
+            throw error;
+        }
+        for (const subscriber of generation.subscribers) {
+            subscriber.onError?.(error);
+        }
+    });
+    return generation;
+}
+function dispatch(generation, event, filePath) {
+    if (current !== generation) {
+        return;
+    }
+    const entry = generation.entries.get(toWatchKey(filePath));
+    if (!entry) {
+        return;
+    }
+    if (event === 'unlink') {
+        // chokidar let go of the path; add it again so that its coming back is seen.
+        entry.watched = false;
+        entry.gaveUp = false;
+        generation.watcher.add(entry.path);
+    }
+    for (const subscriber of entry.subscribers) {
+        subscriber.listener(entry.path, event);
+    }
+}
+async function update(subscriber, filePaths) {
+    if (subscriber.closed) {
+        return;
+    }
+    const { generation } = subscriber;
+    const next = new Map();
+    for (const filePath of filePaths) {
+        next.set(toWatchKey(filePath), filePath);
+    }
+    for (const key of subscriber.keys) {
+        if (!next.has(key)) {
+            release(generation, subscriber, key);
+        }
+    }
+    const joined = [];
+    for (const [key, filePath] of next) {
+        let entry = generation.entries.get(key);
+        if (!entry) {
+            entry = { path: filePath, subscribers: new Set(), watched: false, gaveUp: false };
+            generation.entries.set(key, entry);
+            generation.watcher.add(filePath);
+        }
+        entry.subscribers.add(subscriber);
+        joined.push(entry);
+    }
+    subscriber.keys = new Set(next.keys());
+    await untilWatched(generation, joined);
+}
+function release(generation, subscriber, key) {
+    const entry = generation.entries.get(key);
+    if (!entry) {
+        return;
+    }
+    entry.subscribers.delete(subscriber);
+    if (entry.subscribers.size === 0) {
+        generation.entries.delete(key);
+        // A file path only: see the module JSDoc.
+        generation.watcher.unwatch(entry.path);
+    }
+}
+async function close(subscriber) {
+    if (subscriber.closed) {
+        return;
+    }
+    subscriber.closed = true;
+    const { generation } = subscriber;
+    for (const key of subscriber.keys) {
+        release(generation, subscriber, key);
+    }
+    subscriber.keys = new Set();
+    generation.subscribers.delete(subscriber);
+    if (generation.subscribers.size === 0) {
+        if (current === generation) {
+            current = null;
+        }
+        await generation.watcher.close();
+    }
+}
+async function untilWatched(generation, entries) {
+    let pending = entries.filter(entry => !entry.watched && !entry.gaveUp);
+    const deadline = Date.now() + ARM_TIMEOUT_MS;
+    while (pending.length > 0 && current === generation) {
+        const watched = generation.watcher.getWatched();
+        pending = pending.filter(entry => {
+            entry.watched = isWatched(watched, entry.path);
+            return !entry.watched;
+        });
+        if (pending.length === 0) {
+            break;
+        }
+        if (Date.now() >= deadline) {
+            for (const entry of pending) {
+                entry.gaveUp = true;
+            }
+            break;
+        }
+        await new Promise(resolve => setTimeout(resolve, 1));
+    }
+}
+/**
+ * Whether chokidar has set up watching for `filePath`: it lists the file under
+ * its directory once it holds a handle on it; and for a file that does not
+ * exist yet it watches the nearest existing ancestor directory (listing it
+ * under *its* parent) for the file to appear.
+ */
+function isWatched(watched, filePath) {
+    let target = filePath;
+    while (true) {
+        const directory = path.dirname(target);
+        if (watched[directory]?.includes(path.basename(target))) {
+            return true;
+        }
+        if (directory === target) {
+            return false;
+        }
+        target = directory;
+    }
+}

package/lib/cli/command.js

@@ -68,7 +68,34 @@ export async function command(files, options, apiOptions) {
     // across the whole run (not per file).
     const seenConfigMessages = new Set();
     const filesContent = new Map();
-    const engines = new Map();
+    // Suppressions scope computation is the only consumer of the parsed
+    // documents, so a document is retained past its file's own iteration only
+    // when that computation will run (--suppress, or a non-empty suppressions
+    // file in a normal run). Retaining every file's document otherwise keeps N
+    // DOM trees reachable until the command ends.
+    //
+    // A normal run reads the suppressions file exactly once, here, and applies
+    // that same snapshot at the end: deciding retention from one read and
+    // applying from a later one could disagree if the file changed mid-run,
+    // leaving `applySuppressions` without the node lists it needs.
+    const suppressionsFilePath = resolveSuppressionsPath(options.suppressionsLocation);
+    let normalRunSuppressions = {};
+    let suppressionsReadError;
+    if (!isSuppressMode && !isPruneMode) {
+        try {
+            normalRunSuppressions = await readSuppressionsFile(suppressionsFilePath);
+        }
+        catch (error) {
+            if (isFatalError(error)) {
+                throw error;
+            }
+            // Proceed as if there were no suppressions; only the progressive
+            // output check below treats an unreadable file as an error.
+            suppressionsReadError = error;
+        }
+    }
+    const needsScope = isSuppressMode || Object.keys(normalRunSuppressions).length > 0;
+    const nodeLists = new Map();
     // Shared across every file in this run so its config cache — keyed by
     // resolved config `names`, not by target file — actually helps: config
     // loading/merging/plugin-resolution is done once per distinct config,
@@ -99,9 +126,10 @@ export async function command(files, options, apiOptions) {
         progressiveOutput = false;
     }
     if (progressiveOutput && !isSuppressMode && !isPruneMode) {
-        const suppressionsFilePathForCheck = resolveSuppressionsPath(options.suppressionsLocation);
-        const existingSuppressions = await readSuppressionsFile(suppressionsFilePathForCheck);
-        if (Object.keys(existingSuppressions).length > 0) {
+        if (suppressionsReadError != null) {
+            throw suppressionsReadError;
+        }
+        if (needsScope) {
             progressiveOutput = false;
         }
     }
@@ -157,8 +185,16 @@ export async function command(files, options, apiOptions) {
             sourceCode: result.sourceCode,
             fixedCode: result.fixedCode,
         });
-        // Store engine for scope computation in suppressions
-        engines.set(result.filePath, engine);
+        if (needsScope) {
+            const doc = engine.document;
+            if (doc) {
+                // MLNode structurally satisfies PositionedNode (startLine, startCol, localName,
+                // id, classList, parentElement, children are all present). The double cast is
+                // needed because TypeScript can't verify structural compatibility between the
+                // generic MLNode<T,O> and the plain PositionedNode interface at compile time.
+                nodeLists.set(result.filePath, doc.nodeList);
+            }
+        }
         // In fix mode, report the violations remaining in the FIXED code
         // (re-verified by ml-core) instead of the pre-fix violations, so that
         // the exit code and suppressions reflect the written output.
@@ -197,20 +233,7 @@ export async function command(files, options, apiOptions) {
         }
     }
     // --- Suppressions handling ---
-    const suppressionsFilePath = resolveSuppressionsPath(options.suppressionsLocation);
     const collectedViolationsByFile = collector.groupByFile();
-    // Build nodeLists map from engines for scope computation
-    const nodeLists = new Map();
-    for (const [filePath, engine] of engines) {
-        const doc = engine.document;
-        if (doc) {
-            // MLNode structurally satisfies PositionedNode (startLine, startCol, localName,
-            // id, classList, parentElement, children are all present). The double cast is
-            // needed because TypeScript can't verify structural compatibility between the
-            // generic MLNode<T,O> and the plain PositionedNode interface at compile time.
-            nodeLists.set(filePath, doc.nodeList);
-        }
-    }
     if (isSuppressMode) {
         // Suppress mode: generate/update suppressions file
         const existing = await readSuppressionsFile(suppressionsFilePath);
@@ -250,10 +273,8 @@ export async function command(files, options, apiOptions) {
     let outputViolationsByFile = collectedViolationsByFile;
     let suppressionsApplied = false;
     try {
-        await fs.access(suppressionsFilePath);
-        const suppressionsData = await readSuppressionsFile(suppressionsFilePath);
-        if (Object.keys(suppressionsData).length > 0) {
-            const { filtered, unusedEntries } = applySuppressions(collectedViolationsByFile, suppressionsData, suppressionsFilePath, { nodeLists });
+        if (needsScope) {
+            const { filtered, unusedEntries } = applySuppressions(collectedViolationsByFile, normalRunSuppressions, suppressionsFilePath, { nodeLists });
             outputViolationsByFile = filtered;
             suppressionsApplied = true;
             if (unusedEntries.length > 0) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "markuplint",
-	"version": "5.0.1",
+	"version": "5.1.0",
 	"description": "An HTML linter for all markup developers",
 	"author": "Yusuke Hirao",
 	"license": "MIT",
@@ -35,17 +35,17 @@
 		"clean": "tsc --build --clean tsconfig.build.json"
 	},
 	"dependencies": {
-		"@markuplint/cli-utils": "5.0.1",
-		"@markuplint/file-resolver": "5.0.1",
-		"@markuplint/html-parser": "5.0.1",
-		"@markuplint/html-spec": "5.0.1",
-		"@markuplint/i18n": "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/rules": "5.0.1",
-		"@markuplint/shared": "5.0.1",
+		"@markuplint/cli-utils": "5.1.0",
+		"@markuplint/file-resolver": "5.1.0",
+		"@markuplint/html-parser": "5.1.0",
+		"@markuplint/html-spec": "5.1.0",
+		"@markuplint/i18n": "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/rules": "5.1.0",
+		"@markuplint/shared": "5.1.0",
 		"@types/debug": "4.1.13",
 		"chokidar": "5.0.0",
 		"debug": "4.4.3",
@@ -55,5 +55,5 @@
 		"strip-ansi": "7.2.0",
 		"type-fest": "5.6.0"
 	},
-	"gitHead": "edbaeedca5588fb291ea9d4e21a4ab2bf41fc9cb"
+	"gitHead": "3a061784a8211034ad0c1cbd64798c0213414f65"
 }