markuplint 5.0.0-rc.4 → 5.0.0-rc.6

package/CHANGELOG.md

@@ -3,6 +3,89 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-rc.6](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.5...v5.0.0-rc.6) (2026-08-30)
+
+### Bug Fixes
+
+- add no-aria-hidden-on-hidden-until-found rule (closes [#3999](https://github.com/markuplint/markuplint/issues/3999)) ([#4017](https://github.com/markuplint/markuplint/issues/4017)) ([3dfb300](https://github.com/markuplint/markuplint/commit/3dfb3001dc66452918d5cebbb071244b68779b30))
+- resolveConfig(false) crashes with inline config (not a file path) ([#4018](https://github.com/markuplint/markuplint/issues/4018)) ([7e38b64](https://github.com/markuplint/markuplint/commit/7e38b64caa8cca69009ee765e4aada37fc48c559)), closes [#4015](https://github.com/markuplint/markuplint/issues/4015) [#4015](https://github.com/markuplint/markuplint/issues/4015)
+
+### Features
+
+- split rule-deprecation notices out of config-error ([#4013](https://github.com/markuplint/markuplint/issues/4013)) ([812e6f3](https://github.com/markuplint/markuplint/commit/812e6f356839af8f257cfd91e6b16cfdfdd7cf33))
+
+### Performance Improvements
+
+- share ConfigProvider across a run's files, fix latent overrides caching bug ([#4016](https://github.com/markuplint/markuplint/issues/4016)) ([fcc1875](https://github.com/markuplint/markuplint/commit/fcc1875b1a984a5ef1bb36aa04e7b3522fefc58e)), closes [#3997](https://github.com/markuplint/markuplint/issues/3997) [#3997](https://github.com/markuplint/markuplint/issues/3997)
+
+### BREAKING CHANGES
+
+- `ConfigProvider#resolve(targetFile, names, false)` no longer
+  clears the provider's store/cache/plugin-resolution caches by itself. Callers
+  that relied on `cache: false` alone to force a fresh re-read must now call
+  the new `ConfigProvider#invalidate()` first.
+- violations for deprecated rule names now have
+  `ruleId: 'rule-deprecation'` instead of `ruleId: 'config-error'`. Any
+  consumer filtering `MLCore.verify()` output (or the markuplint CLI/API) by
+  `ruleId === 'config-error'` to catch deprecation messages must also check
+  for `rule-deprecation`.
+
+- feat(markuplint): add --severity-deprecation CLI flag
+
+Wires the new severity.deprecation config option (@markuplint/ml-config)
+and the rule-deprecation ruleId (@markuplint/ml-core) through the CLI:
+
+- --severity-deprecation flag, mirroring --severity-parse-error
+- --show-config details now also surfaces ruleDeprecations
+- per-run dedupe and failed-file counting generalized to cover both
+  config-level ruleIds (config-error and rule-deprecation), not just
+  config-error
+
+* docs(website): document severity.deprecation (EN + JA)
+
+# [5.0.0-rc.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Bug Fixes
+
+- **markuplint:** report post-fix violations for exit code and suppressions ([03855d6](https://github.com/markuplint/markuplint/commit/03855d6641ae736b65994fa6123e91779d2eb41e)), closes [#3890](https://github.com/markuplint/markuplint/issues/3890)
+- **markuplint:** stop repeating config-error messages once per file ([#4007](https://github.com/markuplint/markuplint/issues/4007)) ([466193d](https://github.com/markuplint/markuplint/commit/466193d286628f69e0d99fc8b2f66028523025aa)), closes [#4006](https://github.com/markuplint/markuplint/issues/4006)
+- **pretenders:** resolve same-named components via imports, not scan order ([#3957](https://github.com/markuplint/markuplint/issues/3957)) ([d46a514](https://github.com/markuplint/markuplint/commit/d46a5148c4d7afb156962f4ed795f40a9324e6c5)), closes [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951)
+- **rules:** surface disallowed-element reason via reasonOnly (close [#3815](https://github.com/markuplint/markuplint/issues/3815)) ([#3986](https://github.com/markuplint/markuplint/issues/3986)) ([0142cec](https://github.com/markuplint/markuplint/commit/0142cec667f70fee086f2a6e06d7a26e66bda380))
+- **types): strict charset=utf-8; feat(rules:** usemap-references-map ([#3969](https://github.com/markuplint/markuplint/issues/3969)) ([c63070e](https://github.com/markuplint/markuplint/commit/c63070e29ccb283da7468b2fc67db372ebfcf42a)), closes [#3945](https://github.com/markuplint/markuplint/issues/3945) [#3966](https://github.com/markuplint/markuplint/issues/3966) [#3966](https://github.com/markuplint/markuplint/issues/3966) [#3928](https://github.com/markuplint/markuplint/issues/3928)
+
+### Code Refactoring
+
+- **rules:** redesign v5 rule system — naming, splits, specConformance ([#3989](https://github.com/markuplint/markuplint/issues/3989)) ([e925565](https://github.com/markuplint/markuplint/commit/e925565ce537848d7d1573369723cbce724a841b)), closes [#4](https://github.com/markuplint/markuplint/issues/4) [#aside-conditional-role-mapping-aria-13](https://github.com/markuplint/markuplint/issues/aside-conditional-role-mapping-aria-13)
+
+- feat(markuplint)!: stop forcing severity.parseError default in CLI ([79ff00b](https://github.com/markuplint/markuplint/commit/79ff00b5d068802f4d7e0d8d30ee63e55b8bc7f1)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844)
+
+### Features
+
+- add `pretenders.auto` for on-demand import-graph resolution ([#3962](https://github.com/markuplint/markuplint/issues/3962)) ([5870671](https://github.com/markuplint/markuplint/commit/58706711a20c12cff080d49359f3f6443345eca3)), closes [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3959](https://github.com/markuplint/markuplint/issues/3959) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3957](https://github.com/markuplint/markuplint/issues/3957) [#3959](https://github.com/markuplint/markuplint/issues/3959) [#3951](https://github.com/markuplint/markuplint/issues/3951) [#3951](https://github.com/markuplint/markuplint/issues/3951)
+- **config-presets:** forbid <base> after <link> or <script> in <head> ([#3925](https://github.com/markuplint/markuplint/issues/3925)) ([ceb892d](https://github.com/markuplint/markuplint/commit/ceb892d64772d459a6bd9564684218e3afbdec2e))
+- **rules:** add form-attr-references-form rule ([6b541f0](https://github.com/markuplint/markuplint/commit/6b541f032b76c3712c99ea35596b6b0aa79b6137))
+- **rules:** add input-button-non-empty-value rule ([2cc73dd](https://github.com/markuplint/markuplint/commit/2cc73ddd0f874fae9faf005f498d73fa364b682c))
+- **rules:** add input-file-empty-value rule ([228cbd7](https://github.com/markuplint/markuplint/commit/228cbd752956d3df8f525e4f19f9278a44d87160))
+- **rules:** add input-list-references-datalist rule ([#3931](https://github.com/markuplint/markuplint/issues/3931)) ([bf4ef54](https://github.com/markuplint/markuplint/commit/bf4ef54a1b2937ecbe05fbe5121ddfe199781a95))
+- **rules:** add label-for-references-labelable rule ([#3932](https://github.com/markuplint/markuplint/issues/3932)) ([3713e6b](https://github.com/markuplint/markuplint/commit/3713e6b435a76fe03a941a36a5e33c0ab06c9a80)), closes [#3918](https://github.com/markuplint/markuplint/issues/3918)
+- **rules:** add label-no-multiple-controls rule ([5da3f85](https://github.com/markuplint/markuplint/commit/5da3f8523dd6ffd9f44ea73d9012952aad85d821))
+- **rules:** add map-id-name-match rule ([1472daf](https://github.com/markuplint/markuplint/commit/1472daf62470bf56c4cb326ab47dc43ba87a8cb3))
+- **rules:** add no-extra-selected-options rule ([3ea75ac](https://github.com/markuplint/markuplint/commit/3ea75ac0b6850c36d5419924b18c1002dfb864a9))
+- **rules:** add progress-value-bounds rule ([#3926](https://github.com/markuplint/markuplint/issues/3926)) ([1e259ec](https://github.com/markuplint/markuplint/commit/1e259ec9929ceb3c7ac5864ce2807420646e9602))
+- **rules:** add wai-aria-tab-requires-tabpanel rule ([#3955](https://github.com/markuplint/markuplint/issues/3955)) ([eac9abe](https://github.com/markuplint/markuplint/commit/eac9abef20ef304c3da2114849686b9cf0733942))
+- **rules:** surface parse5-silent HTML LS parse errors (close nu-only umbrella [#3943](https://github.com/markuplint/markuplint/issues/3943)) ([#3980](https://github.com/markuplint/markuplint/issues/3980)) ([89951fa](https://github.com/markuplint/markuplint/commit/89951fa274007d56370510cb0cf11aead808ce13))
+- wire script-content into preset, bench, and default-rules ([dd0507a](https://github.com/markuplint/markuplint/commit/dd0507a9f54fcff25dba666a1c8fbc082489bdc8))
+
+### BREAKING CHANGES
+
+- **rules:** with no alias coverage.
+- CLI invocations that previously relied on the implicit
+  \`severity.parseError: 'error'\` default for _fatal_ parser errors are
+  unaffected — fatal errors continue to emit at \`'error'\` regardless. But
+  projects that lint malformed HTML and expected non-fatal parse5 events to
+  show up by default must now pass \`--severity-parse-error error\` (or set
+  \`severity.parseError\` in their config).
+
 # [5.0.0-rc.4](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.3...v5.0.0-rc.4) (2026-04-19)
 
 **Note:** Version bump only for package markuplint

package/README.md

@@ -25,7 +25,7 @@
 $ npx markuplint target.html
 ```
 
-Supported for _Node.js_ `v22.0.0` or later.
+Supported for _Node.js_ `v24.0.0` or later.
 
 ## Usage
 
@@ -87,6 +87,7 @@ Options
 	--verbose                              Output with detailed information.
 	--include-node-modules                 Include files in node_modules directory. Default: false.
 	--severity-parse-error                 Specifies the severity level of parse errors. Supports "error", "warning", and "off". Default: "error".
+	--severity-deprecation                 Specifies the severity level of deprecated rule name notices. Supports "error", "warning", and "off". Default: "warning".
 	--max-count                            Limit the number of violations shown. Default: 0 (no limit).
 	--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).
 	--progressive-output                   Output results immediately after processing each file. Default: false.
@@ -138,7 +139,7 @@ $ markuplint --prune-suppressions "src/**/*.html"
 ```json
 {
   "src/index.html": {
-    "attr-duplication": { "count": 3, "scope": "#main-nav > ul" }
+    "no-duplicate-attr": { "count": 3, "scope": "#main-nav > ul" }
   }
 }
 ```

package/lib/api/lint.d.ts

@@ -4,6 +4,11 @@ import type { Target } from '@markuplint/file-resolver';
 /**
  * Lints multiple targets (files or inline sources) and returns results for each.
  *
+ * Config-level violations (broken config, deprecated rule names) are deduped
+ * per call the same way the CLI dedupes them per run: a message identical
+ * across every file sharing one config is kept only in the first file's
+ * result, not repeated in every file's `violations` array. See #3997.
+ *
  * @param targetList - An array of file paths/globs or inline source code targets
  * @param options - API options for configuration, locale, rules, and behavior
  * @returns An array of lint results, one per processed file

package/lib/api/lint.js

@@ -1,8 +1,14 @@
-import { resolveFiles } from '@markuplint/file-resolver';
+import { ConfigProvider, resolveFiles } from '@markuplint/file-resolver';
+import { dedupeConfigLevelViolations } from '../dedupe-config-violations.js';
 import { MLEngine } from './ml-engine.js';
 /**
  * Lints multiple targets (files or inline sources) and returns results for each.
  *
+ * Config-level violations (broken config, deprecated rule names) are deduped
+ * per call the same way the CLI dedupes them per run: a message identical
+ * across every file sharing one config is kept only in the first file's
+ * result, not repeated in every file's `violations` array. See #3997.
+ *
  * @param targetList - An array of file paths/globs or inline source code targets
  * @param options - API options for configuration, locale, rules, and behavior
  * @returns An array of lint results, one per processed file
@@ -10,13 +16,44 @@ import { MLEngine } from './ml-engine.js';
 export async function lint(targetList, options) {
     const res = [];
     const files = await resolveFiles(targetList);
+    // Shared across every file so `MLEngine`'s config cache — keyed by
+    // resolved config `names`, not by target file — actually helps: see
+    // `ConfigProvider.resolve`'s doc comment and #3997.
+    const configProvider = new ConfigProvider();
+    const seenConfigMessages = new Set();
     for (const file of files) {
-        const engine = new MLEngine(file, options);
+        const engine = new MLEngine(file, { ...options, configProvider });
         const result = await engine.exec();
         if (!result) {
             continue;
         }
-        res.push(result);
+        // Dedupe both views a caller might read: the first-pass `violations`,
+        // and — when fix mode found fixes — `fixSummary.finalPassViolations`
+        // (the post-fix re-verification `command.ts` prefers when reporting
+        // fixed results). Both arrays describe the SAME file, so they always
+        // carry the same config-level messages — that's not a repeat worth
+        // suppressing. Only a *later file* repeating a message already kept
+        // (in either array) is. So both arrays are deduped against the same
+        // pre-file snapshot of `seenConfigMessages` (not against each other),
+        // and only after both are done are their combined discoveries folded
+        // back into `seenConfigMessages` for the next file. The snapshot is
+        // only taken when there's a second array to protect against — most
+        // files (no fix mode, or fix mode with nothing to fix) have none.
+        let finalPassViolations = result.fixSummary?.finalPassViolations;
+        const seenBeforeThisFile = finalPassViolations ? new Set(seenConfigMessages) : undefined;
+        const violations = dedupeConfigLevelViolations(result.violations, seenConfigMessages);
+        if (finalPassViolations && seenBeforeThisFile) {
+            const seenForFinalPass = new Set(seenBeforeThisFile);
+            finalPassViolations = dedupeConfigLevelViolations(finalPassViolations, seenForFinalPass);
+            for (const key of seenForFinalPass) {
+                seenConfigMessages.add(key);
+            }
+        }
+        res.push({
+            ...result,
+            violations,
+            fixSummary: result.fixSummary && { ...result.fixSummary, finalPassViolations },
+        });
     }
     return res;
 }

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

@@ -1,12 +1,44 @@
 import type { APIOptions, MLEngineEventMap } from './types.js';
 import type { MLResultInfo } from '../types.js';
 import type { ConfigSet, MLFile, Target } from '@markuplint/file-resolver';
-import type { PlainData } from '@markuplint/ml-config';
+import type { PlainData, RuleAliasWarning } from '@markuplint/ml-config';
 import type { Document, RuleConfigValue } from '@markuplint/ml-core';
+import { ConfigProvider } from '@markuplint/file-resolver';
 import { Emitter } from 'strict-event-emitter';
 type MLEngineOptions = {
     readonly debug?: boolean;
     readonly watch?: boolean;
+    /**
+     * A pre-built {@link ConfigProvider} to resolve config through, instead of
+     * the one this instance would otherwise create for itself.
+     *
+     * `ConfigProvider` caches by the resolved config's `names` (file paths),
+     * not by target file — so a caller looping over many files (the CLI, or
+     * the `lint()` API) that constructs one `MLEngine` per file should share
+     * a single `ConfigProvider` across that loop; every file whose config
+     * resolves to the same `names` then reuses the same cached base config
+     * (merge/validate/plugin-resolution) instead of redoing that work once
+     * per file. See #3997.
+     *
+     * Optional and additive: omitted, each `MLEngine` still creates its own
+     * provider exactly as before.
+     *
+     * **Caveat — `watch: true`**: `resolveConfig()`'s cache-busting
+     * (`cache: false`, used internally on every watch-triggered re-resolve)
+     * calls `ConfigProvider#invalidate()`, which clears the *entire* shared
+     * provider, not anything scoped to one engine or file. `resolveConfig()`
+     * runs through `ConfigProvider#runExclusive()`, so an overlapping call
+     * from another engine can no longer interleave with — and corrupt — this
+     * one's in-flight resolve (see #4015); it can only run *before* or
+     * *after* it. Sharing one `configProvider` across multiple engines that
+     * also have `watch: true` still risks one engine's re-resolve evicting
+     * another's already-cached config, forcing an avoidable re-resolve on
+     * that engine's next lookup. Neither the CLI (which doesn't support
+     * `--watch`) nor `lint()` (which never sets `watch`) create this
+     * combination — it only arises if a direct API consumer builds it
+     * deliberately.
+     */
+    readonly configProvider?: ConfigProvider;
 };
 /**
  * Options for creating an {@link MLEngine} from inline source code.
@@ -17,6 +49,16 @@ export type FromCodeOptions = APIOptions & MLEngineOptions & {
     /** Optional working directory for config resolution */
     readonly dirname?: string;
 };
+/**
+ * A {@link ConfigSet} widened with deprecated-rule-name notices found while
+ * applying {@link applyRuleAliasesToConfig}. Kept structured (not folded
+ * into `errs` as generic `Error`s) so `MLCore` can report them under their
+ * own `rule-deprecation` ruleId instead of `config-error` — see
+ * `packages/@markuplint/ml-core/src/ml-core.ts`'s `verify()`.
+ */
+type ResolvedConfigSet = ConfigSet & {
+    readonly ruleDeprecations: readonly RuleAliasWarning[];
+};
 /**
  * The main markuplint engine that orchestrates file resolution, configuration loading,
  * parsing, and linting. Supports both single-file and watch-mode operation.
@@ -70,6 +112,22 @@ export declare class MLEngine extends Emitter<MLEngineEventMap> {
      * @param enable - Whether to enable watch mode
      */
     watchMode(enable: boolean): void;
-    resolveConfig(cache: boolean): Promise<ConfigSet>;
+    /**
+     * Resolves the configuration set for the target file.
+     *
+     * Public — unlike the other resolution steps, which are private —
+     * because the CLI's `--show-config` needs the computed configuration
+     * without running a lint.
+     *
+     * Precedence contract (highest first): the inline `config` option,
+     * then the explicit `configFile` path, then auto-discovered config files
+     * (search is skipped when `noSearchConfig` or `configFile` is set),
+     * then `defaultConfig`. `markuplint:recommended` applies only when none
+     * of these are provided.
+     *
+     * @param cache - Whether to reuse previously loaded config files
+     * @returns The resolved configuration set
+     */
+    resolveConfig(cache: boolean): Promise<ResolvedConfigSet>;
 }
 export {};

package/lib/api/ml-engine.js

@@ -1,6 +1,7 @@
-import { ConfigProvider, resolveFiles, resolveParser, resolvePretenders, resolveRules, resolveSpecs, } from '@markuplint/file-resolver';
-import { mergeConfig } from '@markuplint/ml-config';
+import { ConfigProvider, disambiguatePretendersForFile, invalidatePretenderResolutionCaches, resolveFiles, resolveParser, resolvePretenders, resolveRules, resolveSpecs, } from '@markuplint/file-resolver';
+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';
@@ -9,6 +10,15 @@ import { i18n } from '../i18n.js';
 const log = coreLog.extend('ml-engine');
 const fileLog = log.extend('file');
 const configLog = log.extend('config');
+/**
+ * The config passed to {@link ConfigProvider.set} when no config was
+ * discovered, requested, or provided by the caller. A module-level constant
+ * (not rebuilt per call) so its object identity is stable — letting
+ * `ConfigProvider.set`'s auto-key cache (keyed by identity) recognize repeat
+ * calls across every file in a run sharing one `ConfigProvider`, the same
+ * way a stable `options.config`/`defaultConfig` reference does. See #3997.
+ */
+const RECOMMENDED_CONFIG = { extends: ['markuplint:recommended'] };
 /**
  * The main markuplint engine that orchestrates file resolution, configuration loading,
  * parsing, and linting. Supports both single-file and watch-mode operation.
@@ -62,7 +72,7 @@ export class MLEngine extends Emitter {
         }
         this.#file = file;
         this.#options = options;
-        this.#configProvider = new ConfigProvider();
+        this.#configProvider = options?.configProvider ?? new ConfigProvider();
         this.watchMode(!!this.#options?.watch);
         log('[MLEngine] Initialized: %s', this.#file.path);
     }
@@ -224,6 +234,7 @@ export class MLEngine extends Emitter {
                     plugins: [],
                     files: new Set(),
                     errs: [error],
+                    ruleDeprecations: [],
                 };
             }
             else {
@@ -256,7 +267,7 @@ export class MLEngine extends Emitter {
             ...configSet.config.severity,
             ...this.#options?.severity,
         };
-        const pretenders = await this.#resolvePretenders(configSet);
+        const pretenders = await this.#resolvePretenders(configSet, cache);
         fileLog('Resolved pretenders: %O', pretenders);
         const ruleset = this.#resolveRuleset(configSet);
         fileLog('Resolved ruleset: %O', ruleset);
@@ -291,33 +302,83 @@ export class MLEngine extends Emitter {
             locale,
             ruleCommonSettings,
             configErrors: configSet.errs,
+            ruleDeprecations: configSet.ruleDeprecations,
         };
     }
+    /**
+     * Resolves the configuration set for the target file.
+     *
+     * Public — unlike the other resolution steps, which are private —
+     * because the CLI's `--show-config` needs the computed configuration
+     * without running a lint.
+     *
+     * Precedence contract (highest first): the inline `config` option,
+     * then the explicit `configFile` path, then auto-discovered config files
+     * (search is skipped when `noSearchConfig` or `configFile` is set),
+     * then `defaultConfig`. `markuplint:recommended` applies only when none
+     * of these are provided.
+     *
+     * @param cache - Whether to reuse previously loaded config files
+     * @returns The resolved configuration set
+     */
     async resolveConfig(cache) {
         this.emit('log', 'resolveConfig', JSON.stringify(this.#configProvider, null, 2));
         configLog('configProvider: %s', this.#configProvider);
-        const defaultConfigKey = this.#options?.defaultConfig && this.#configProvider.set(mergeConfig(this.#options?.defaultConfig));
-        configLog('defaultConfigKey: %s', defaultConfigKey ?? 'N/A');
-        this.emit('log', 'defaultConfigKey', defaultConfigKey ?? 'N/A');
-        const targetConfig = await this.#configProvider.search(this.#file);
-        this.emit('log', 'targetConfig', targetConfig ?? 'N/A');
-        const configFilePathsFromTarget = this.#options?.noSearchConfig || this.#options?.configFile
-            ? (defaultConfigKey ?? null)
-            : (targetConfig ?? defaultConfigKey);
-        configLog('configFilePathsFromTarget: %s', configFilePathsFromTarget ?? 'N/A');
-        this.emit('log', 'configFilePathsFromTarget', configFilePathsFromTarget ?? 'N/A');
-        const configKey = this.#options?.config && this.#configProvider.set(mergeConfig(this.#options.config));
-        configLog('option.config: %s', configKey ?? 'N/A');
-        this.emit('log', 'option.config', configFilePathsFromTarget ?? 'N/A');
-        let defaultRecommended = null;
-        if (!defaultConfigKey && !configFilePathsFromTarget && !configKey && !this.#options?.configFile) {
-            // No configured
-            // Default: set recommended
-            defaultRecommended = this.#configProvider.set({ extends: ['markuplint:recommended'] });
-        }
-        configLog('defaultRecommended: %s', defaultRecommended ?? 'N/A');
-        this.emit('log', 'defaultRecommended', defaultRecommended ?? 'N/A');
-        const configSet = await this.#configProvider.resolve(this.#file, [configFilePathsFromTarget, this.#options?.configFile, configKey, defaultRecommended], cache);
+        // Runs the whole invalidate → set → search → resolve sequence as one
+        // exclusive unit on the provider — an overlapping call on the same
+        // (possibly shared, e.g. two watch-triggered re-resolves close
+        // together) `ConfigProvider` must not interleave its own `invalidate()`
+        // in the middle of this one's `set()`/`search()` calls, which would
+        // wipe the keys just registered below before `resolve()` gets to use
+        // them. See #4015.
+        const resolvedConfigSet = await this.#configProvider.runExclusive(async () => {
+            if (!cache) {
+                // Must run before any `set()` call below — `ConfigProvider#resolve()`
+                // no longer clears its own store on `cache: false`, so invalidating
+                // after registering this call's inline config would discard it
+                // again immediately. See #4015.
+                this.#configProvider.invalidate();
+            }
+            const defaultConfigKey = this.#options?.defaultConfig &&
+                this.#configProvider.set(mergeConfig(this.#options.defaultConfig), undefined, this.#options.defaultConfig);
+            configLog('defaultConfigKey: %s', defaultConfigKey ?? 'N/A');
+            this.emit('log', 'defaultConfigKey', defaultConfigKey ?? 'N/A');
+            const targetConfig = await this.#configProvider.search(this.#file);
+            this.emit('log', 'targetConfig', targetConfig ?? 'N/A');
+            const configFilePathsFromTarget = this.#options?.noSearchConfig || this.#options?.configFile
+                ? (defaultConfigKey ?? null)
+                : (targetConfig ?? defaultConfigKey);
+            configLog('configFilePathsFromTarget: %s', configFilePathsFromTarget ?? 'N/A');
+            this.emit('log', 'configFilePathsFromTarget', configFilePathsFromTarget ?? 'N/A');
+            const configKey = this.#options?.config &&
+                this.#configProvider.set(mergeConfig(this.#options.config), undefined, this.#options.config);
+            configLog('option.config: %s', configKey ?? 'N/A');
+            this.emit('log', 'option.config', configFilePathsFromTarget ?? 'N/A');
+            let defaultRecommended = null;
+            if (!defaultConfigKey && !configFilePathsFromTarget && !configKey && !this.#options?.configFile) {
+                // No configured
+                // Default: set recommended
+                defaultRecommended = this.#configProvider.set(RECOMMENDED_CONFIG);
+            }
+            configLog('defaultRecommended: %s', defaultRecommended ?? 'N/A');
+            this.emit('log', 'defaultRecommended', defaultRecommended ?? 'N/A');
+            return this.#configProvider.resolve(this.#file, [configFilePathsFromTarget, this.#options?.configFile, configKey, defaultRecommended], cache);
+        });
+        // Rewrite deprecated rule names (v5 rule-system redesign, #3989) to
+        // their current replacement(s) so old configurations keep working.
+        // Applied once, here, after `extends` is fully merged — everything
+        // downstream (Ruleset, rule resolution, `--show-config`) sees only
+        // current rule names. Covers all three places a rule name can appear:
+        // the top-level `rules` map, and each `nodeRules`/`childNodeRules`
+        // entry's own `rules`.
+        const { config: aliasedConfig, warnings: ruleAliasWarnings } = applyRuleAliasesToConfig(resolvedConfigSet.config, ruleAliasTable);
+        // Kept structured (not folded into `errs` as generic `Error`s) so
+        // `MLCore` can report these under their own `rule-deprecation` ruleId,
+        // separate from genuine config-validation failures — see
+        // `ResolvedConfigSet`'s doc comment.
+        const configSet = ruleAliasWarnings.length === 0
+            ? { ...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.
@@ -335,10 +396,22 @@ export class MLEngine extends Emitter {
     }
     async #resolvePretenders(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-    configSet) {
-        const pretenders = await resolvePretenders(configSet.config.pretenders);
-        fileLog('Resolved pretenders: %O', pretenders);
-        return pretenders;
+    configSet, cache) {
+        if (!cache) {
+            // A cache-busting re-resolve (e.g. watch mode after a file change) must also
+            // invalidate `@markuplint/pretenders`' own module-level resolution caches —
+            // otherwise a renamed export or a newly valid tsconfig `paths` alias keeps
+            // resolving as it did before the change for the rest of the process's lifetime.
+            await invalidatePretenderResolutionCaches();
+        }
+        const sourceCode = await this.#file.getCode();
+        const pretenders = await resolvePretenders(configSet.config.pretenders, {
+            filePath: this.#file.path,
+            sourceCode,
+        });
+        const disambiguated = await disambiguatePretendersForFile(this.#file.path, sourceCode, pretenders);
+        fileLog('Resolved pretenders: %O', disambiguated);
+        return disambiguated;
     }
     async #resolveRules(plugins, ruleset) {
         const rules = await resolveRules(plugins, ruleset, this.#options?.importPresetRules ?? true);

package/lib/cli/bootstrap.d.ts

@@ -1,13 +1,5 @@
 import type { ReadonlyDeep } from 'type-fest';
-/**
- * Help text displayed when the CLI is invoked with `--help` or without arguments.
- * Documents all available options, flags, and usage examples.
- */
-export declare const help = "\nUsage\n\t$ markuplint <HTML file paths (glob format)>\n\t$ <stdout> | markuplint\n\nOptions\n\t--config,                -c FILE_PATH  A configuration file path.\n\t--fix,                                 Fix HTML.\n\t--fix-dry-run                          Show what --fix would change without writing files.\n\t--format,                -f FORMAT     Output format. Support \"JSON\", \"Simple\", \"GitHub\" and \"Standard\". Default: \"Standard\".\n\t--no-search-config                     No search a configure file automatically.\n\t--ignore-ext                           Evaluate files that are received even though the type of extension.\n\t--no-import-preset-rules               No import preset rules.\n\t--locale                               Locale of the message of violation. Default is an OS setting.\n\t--no-color,                            Output no color.\n\t--problem-only,          -p            Output only problems, without passeds.\n\t--no-allow-warnings                    Return status code 1 even if there are warnings.\n\t--allow-empty-input                    Return status code 1 even if there are no input files.\n\t--show-config                          Output computed configuration of the target file. Supports \"details\" and empty. Default: empty.\n\t--verbose                              Output with detailed information.\n\t--include-node-modules                 Include files in node_modules directory. Default: false.\n\t--severity-parse-error                 Specifies the severity level of parse errors. Supports \"error\", \"warning\", and \"off\". Default: \"error\".\n\t--max-count                            Limit the number of violations shown. Default: 0 (no limit).\n\t--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).\n\t--progressive-output                   Output results immediately after processing each file. Default: false.\n\n\t--suppress                             [Experimental] Generate/update suppressions file for all current errors.\n\t--suppress-rule RULE_ID                [Experimental] Suppress only the specified rule.\n\t--prune-suppressions                   [Experimental] Remove stale entries from the suppressions file.\n\t--suppressions-location PATH           [Experimental] Custom path for the suppressions file. Default: \"markuplint-suppressions.json\".\n\n\t--init                                 Initialize settings interactively.\n\t--search                               Search lines of codes that include the target element by selectors.\n\n\t--help,                  -h            Show help.\n\t--version,               -v            Show version.\n\nExamples\n\t$ markuplint verifyee.html --config path/to/.markuplintrc\n\t$ cat verifyee.html | markuplint\n";
-/**
- * The parsed CLI instance created by `meow`, providing access to
- * positional arguments (`cli.input`) and parsed flags (`cli.flags`).
- */
+export declare const help = "\nUsage\n\t$ markuplint <HTML file paths (glob format)>\n\t$ <stdout> | markuplint\n\nOptions\n\t--config,                -c FILE_PATH  A configuration file path.\n\t--fix,                                 Fix HTML.\n\t--fix-dry-run                          Show what --fix would change without writing files.\n\t--format,                -f FORMAT     Output format. Support \"JSON\", \"Simple\", \"GitHub\" and \"Standard\". Default: \"Standard\".\n\t--no-search-config                     No search a configure file automatically.\n\t--ignore-ext                           Evaluate files that are received even though the type of extension.\n\t--no-import-preset-rules               No import preset rules.\n\t--locale                               Locale of the message of violation. Default is an OS setting.\n\t--no-color,                            Output no color.\n\t--problem-only,          -p            Output only problems, without passeds.\n\t--no-allow-warnings                    Return status code 1 even if there are warnings.\n\t--allow-empty-input                    Return status code 1 even if there are no input files.\n\t--show-config                          Output computed configuration of the target file. Supports \"details\" and empty. Default: empty.\n\t--verbose                              Output with detailed information.\n\t--include-node-modules                 Include files in node_modules directory. Default: false.\n\t--severity-parse-error                 Severity for the built-in parse-error channel. Supports \"error\", \"warning\", and \"off\". Unset by default: fatal ParserErrors emit at \"error\" and non-fatal parse5 events are off (opt-in per code via config).\n\t--severity-deprecation                 Severity for the built-in rule-deprecation channel (deprecated rule names). Supports \"error\", \"warning\", and \"off\". Default: \"warning\".\n\t--max-count                            Limit the number of violations shown. Default: 0 (no limit).\n\t--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).\n\t--no-progressive-output                Wait until every file is processed before outputting results. Default: false (output progressively).\n\n\t--suppress                             [Experimental] Generate/update suppressions file for all current errors.\n\t--suppress-rule RULE_ID                [Experimental] Suppress only the specified rule.\n\t--prune-suppressions                   [Experimental] Remove stale entries from the suppressions file.\n\t--suppressions-location PATH           [Experimental] Custom path for the suppressions file. Default: \"markuplint-suppressions.json\".\n\n\t--init                                 Initialize settings interactively.\n\t--search                               Search lines of codes that include the target element by selectors.\n\n\t--help,                  -h            Show help.\n\t--version,               -v            Show version.\n\nExamples\n\t$ markuplint verifyee.html --config path/to/.markuplintrc\n\t$ cat verifyee.html | markuplint\n";
 export declare const cli: import("meow").Result<{
     config: {
         type: "string";
@@ -81,7 +73,9 @@ export declare const cli: import("meow").Result<{
     };
     severityParseError: {
         type: "string";
-        default: string;
+    };
+    severityDeprecation: {
+        type: "string";
     };
     maxCount: {
         type: "number";
@@ -93,7 +87,7 @@ export declare const cli: import("meow").Result<{
     };
     progressiveOutput: {
         type: "boolean";
-        default: false;
+        default: true;
     };
     suppress: {
         type: "boolean";
@@ -110,8 +104,4 @@ export declare const cli: import("meow").Result<{
         type: "string";
     };
 }>;
-/**
- * Deeply read-only type representing the parsed CLI flags.
- * Derived from the `meow` flag definitions in {@link cli}.
- */
 export type CLIOptions = ReadonlyDeep<typeof cli.flags>;

package/lib/cli/bootstrap.js

@@ -1,8 +1,4 @@
 import meow from 'meow';
-/**
- * Help text displayed when the CLI is invoked with `--help` or without arguments.
- * Documents all available options, flags, and usage examples.
- */
 export const help = `
 Usage
 	$ markuplint <HTML file paths (glob format)>
@@ -24,10 +20,11 @@ Options
 	--show-config                          Output computed configuration of the target file. Supports "details" and empty. Default: empty.
 	--verbose                              Output with detailed information.
 	--include-node-modules                 Include files in node_modules directory. Default: false.
-	--severity-parse-error                 Specifies the severity level of parse errors. Supports "error", "warning", and "off". Default: "error".
+	--severity-parse-error                 Severity for the built-in parse-error channel. Supports "error", "warning", and "off". Unset by default: fatal ParserErrors emit at "error" and non-fatal parse5 events are off (opt-in per code via config).
+	--severity-deprecation                 Severity for the built-in rule-deprecation channel (deprecated rule names). Supports "error", "warning", and "off". Default: "warning".
 	--max-count                            Limit the number of violations shown. Default: 0 (no limit).
 	--max-warnings                         Number of warnings to trigger nonzero exit code. Default: -1 (no limit).
-	--progressive-output                   Output results immediately after processing each file. Default: false.
+	--no-progressive-output                Wait until every file is processed before outputting results. Default: false (output progressively).
 
 	--suppress                             [Experimental] Generate/update suppressions file for all current errors.
 	--suppress-rule RULE_ID                [Experimental] Suppress only the specified rule.
@@ -44,10 +41,6 @@ Examples
 	$ markuplint verifyee.html --config path/to/.markuplintrc
 	$ cat verifyee.html | markuplint
 `;
-/**
- * The parsed CLI instance created by `meow`, providing access to
- * positional arguments (`cli.input`) and parsed flags (`cli.flags`).
- */
 export const cli = meow(help, {
     importMeta: import.meta,
     flags: {
@@ -123,7 +116,9 @@ export const cli = meow(help, {
         },
         severityParseError: {
             type: 'string',
-            default: 'error',
+        },
+        severityDeprecation: {
+            type: 'string',
         },
         maxCount: {
             type: 'number',
@@ -135,8 +130,7 @@ export const cli = meow(help, {
         },
         progressiveOutput: {
             type: 'boolean',
-            // TODO: It will be changed to `true` in the next major version.
-            default: false,
+            default: true,
         },
         suppress: {
             type: 'boolean',

package/lib/cli/command.d.ts

@@ -1,16 +1,4 @@
 import type { CLIOptions } from './bootstrap.js';
 import type { APIOptions } from '../api/types.js';
 import type { Target } from '@markuplint/file-resolver';
-/**
- * Executes the markuplint linting command against the given files.
- *
- * Resolves file targets, creates an {@link MLEngine} for each file, collects
- * violations, and outputs results in the requested format. When the `--fix`
- * flag is set, overwrites files with their auto-fixed content.
- *
- * @param files - The list of file targets (paths or inline source code) to lint.
- * @param options - CLI options controlling output format, fix mode, locale, and other behaviors.
- * @param apiOptions - Optional overrides for the underlying API (e.g., custom rules or config).
- * @returns `true` if any errors were found (or warnings exceeded the limit), `false` otherwise.
- */
 export declare function command(files: readonly Readonly<Target>[], options: CLIOptions, apiOptions?: APIOptions): Promise<boolean>;