@markuplint/ml-core 5.0.0-rc.5 → 5.0.0-rc.6

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 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)
+
+### 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))
+
+### BREAKING CHANGES
+
+- 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

package/lib/ml-core.d.ts

@@ -2,6 +2,20 @@ import type { MLFabric } from './types.js';
 import type { PlainData, RuleConfigValue, TextEdit, Violation } from '@markuplint/ml-config';
 import { ParserError } from '@markuplint/parser-utils';
 import { Document } from './ml-dom/index.js';
+/**
+ * `ruleId` of a genuinely broken config (unresolved rule reference, plugin
+ * resolution failure, ...). Exported so consumers that need to recognize
+ * config-level violations (e.g. the CLI's per-run dedupe and failed-file
+ * counting in `packages/markuplint/src/cli/command.ts`) reference the same
+ * literal `MLCore.verify()` emits, instead of duplicating the string.
+ */
+export declare const CONFIG_ERROR_RULE_ID = "config-error";
+/**
+ * `ruleId` of a deprecated-but-working rule name notice — see
+ * {@link CONFIG_ERROR_RULE_ID} for why this is exported rather than a
+ * private literal.
+ */
+export declare const RULE_DEPRECATION_RULE_ID = "rule-deprecation";
 /**
  * Summary of the multi-pass fix process.
  */
@@ -74,7 +88,7 @@ export type MLCoreParams = {
  */
 export declare class MLCore {
     #private;
-    constructor({ parser, sourceCode, ruleset, rules, locale, schemas, ruleCommonSettings, parserOptions, severity, pretenders, filename, debug, configErrors, }: MLCoreParams);
+    constructor({ parser, sourceCode, ruleset, rules, locale, schemas, ruleCommonSettings, parserOptions, severity, pretenders, filename, debug, configErrors, ruleDeprecations, }: MLCoreParams);
     /**
      * The parsed document, or a {@link ParserError} if parsing failed.
      */
@@ -91,7 +105,7 @@ export declare class MLCore {
      *
      * @param fabric - Partial fabric with the properties to update
      */
-    update({ parser, ruleset, rules, locale, schemas, parserOptions, pretenders, configErrors }: Partial<MLFabric>): void;
+    update({ parser, ruleset, rules, locale, schemas, parserOptions, pretenders, configErrors, ruleDeprecations, }: Partial<MLFabric>): void;
     /**
      * Runs all configured rules against the parsed document and returns violations.
      *

package/lib/ml-core.js

@@ -4,6 +4,20 @@ import { applyFixes } from './fix-applier.js';
 import { Document } from './ml-dom/index.js';
 import { expandNamedNodeRules, expandNamedRules } from './virtual-rule.js';
 const resultLog = log.extend('result');
+/**
+ * `ruleId` of a genuinely broken config (unresolved rule reference, plugin
+ * resolution failure, ...). Exported so consumers that need to recognize
+ * config-level violations (e.g. the CLI's per-run dedupe and failed-file
+ * counting in `packages/markuplint/src/cli/command.ts`) reference the same
+ * literal `MLCore.verify()` emits, instead of duplicating the string.
+ */
+export const CONFIG_ERROR_RULE_ID = 'config-error';
+/**
+ * `ruleId` of a deprecated-but-working rule name notice — see
+ * {@link CONFIG_ERROR_RULE_ID} for why this is exported rather than a
+ * private literal.
+ */
+export const RULE_DEPRECATION_RULE_ID = 'rule-deprecation';
 /**
  * The core linting engine for markuplint.
  *
@@ -29,6 +43,13 @@ export class MLCore {
      * Set once per construction/`update()` and never mutated by re-parsing.
      */
     #configErrors;
+    /**
+     * Deprecated-rule-name notices, kept structured and separate from
+     * `#configErrors` so `verify()` can report them under their own
+     * `rule-deprecation` ruleId. Set once per construction/`update()`, same
+     * lifecycle as `#configErrors`.
+     */
+    #ruleDeprecations;
     /**
      * Rule-mapping errors for the CURRENT document. Reset (not accumulated) on
      * every `#createDocument()` so repeated `setCode()` calls don't duplicate
@@ -44,7 +65,7 @@ export class MLCore {
     #originalNodeRules;
     #originalChildNodeRules;
     #disabledNamespaces;
-    constructor({ parser, sourceCode, ruleset, rules, locale, schemas, ruleCommonSettings, parserOptions, severity, pretenders, filename, debug, configErrors, }) {
+    constructor({ parser, sourceCode, ruleset, rules, locale, schemas, ruleCommonSettings, parserOptions, severity, pretenders, filename, debug, configErrors, ruleDeprecations, }) {
         if (debug) {
             enableDebug();
         }
@@ -58,6 +79,7 @@ export class MLCore {
         this.#severity = severity;
         this.#pretenders = [...pretenders];
         this.#configErrors = [...(configErrors ?? [])];
+        this.#ruleDeprecations = [...(ruleDeprecations ?? [])];
         // Preserve pre-expansion nodeRules for hot-reload
         this.#originalNodeRules = ruleset.nodeRules ?? [];
         this.#originalChildNodeRules = ruleset.childNodeRules ?? [];
@@ -101,12 +123,13 @@ export class MLCore {
      *
      * @param fabric - Partial fabric with the properties to update
      */
-    update({ parser, ruleset, rules, locale, schemas, parserOptions, pretenders, configErrors }) {
+    update({ parser, ruleset, rules, locale, schemas, parserOptions, pretenders, configErrors, ruleDeprecations, }) {
         this.#parser = parser ?? this.#parser;
         this.#locale = locale ?? this.#locale;
         this.#schemas = schemas ?? this.#schemas;
         this.#pretenders = pretenders ? [...pretenders] : this.#pretenders;
         this.#configErrors = [...(configErrors ?? [])];
+        this.#ruleDeprecations = [...(ruleDeprecations ?? [])];
         const baseRules = rules ? [...rules] : this.#rules.filter(r => !r.baseRuleId);
         const incomingNodeRules = ruleset?.nodeRules ?? this.#originalNodeRules;
         const incomingChildNodeRules = ruleset?.childNodeRules ?? this.#originalChildNodeRules;
@@ -170,7 +193,7 @@ export class MLCore {
             }
             if (!definedRuleName.has(setRuleName)) {
                 configViolations.push({
-                    ruleId: 'config-error',
+                    ruleId: CONFIG_ERROR_RULE_ID,
                     severity: 'warning',
                     message: `Rule not found: ${setRuleName}`,
                     col: 1,
@@ -181,7 +204,7 @@ export class MLCore {
         }
         for (const error of [...this.#configErrors, ...this.#mappingErrors]) {
             configViolations.push({
-                ruleId: 'config-error',
+                ruleId: CONFIG_ERROR_RULE_ID,
                 severity: 'warning',
                 message: error.message,
                 col: 1,
@@ -189,6 +212,19 @@ export class MLCore {
                 raw: '',
             });
         }
+        const deprecationSeverity = this.#resolveDeprecationSeverity();
+        if (deprecationSeverity != null) {
+            for (const { deprecatedName, replacedBy } of this.#ruleDeprecations) {
+                configViolations.push({
+                    ruleId: RULE_DEPRECATION_RULE_ID,
+                    severity: deprecationSeverity,
+                    message: `Rule "${deprecatedName}" is deprecated and will be removed in v6. Use ${replacedBy.join(', ')} instead.`,
+                    col: 1,
+                    line: 1,
+                    raw: '',
+                });
+            }
+        }
         violations.push(...configViolations);
         const ruleViolations = await this.#runAllRules(fix);
         violations.push(...ruleViolations);
@@ -363,6 +399,22 @@ export class MLCore {
             }
         }
     }
+    /**
+     * Resolves `severity.deprecation`, honouring its single-value form only
+     * (unlike `severity.parseError`, there's no fixed enum of deprecated rule
+     * names to key a per-code `Record` on).
+     *
+     * Unlike `#createParseError`'s parse-error channel, this defaults to
+     * `'warning'` (not off/suppressed) when unset — the deprecation channel
+     * is being carved out of the always-on `config-error` channel, not
+     * introduced cold, so leaving the option unset must not silence a notice
+     * users already see today.
+     *
+     * @returns the resolved severity, or `null` if suppressed.
+     */
+    #resolveDeprecationSeverity() {
+        return resolveUniformSeverity(this.#severity.deprecation, 'warning');
+    }
     /**
      * Builds a `ruleId: 'parse-error'` violation, honouring
      * `severity.parseError`.
@@ -377,36 +429,18 @@ export class MLCore {
      */
     #createParseError(message, line, col, raw, code) {
         const cfg = this.#severity.parseError;
-        if (cfg === false || cfg === 'off') {
+        // Fatal ParserErrors (no `code`) can't be targeted by the per-code
+        // Record form, so they fall back to `'error'` there; under the
+        // uniform form they default to `'error'` too, while non-fatal entries
+        // default to suppressed when unset — see `resolveUniformSeverity`.
+        const severity = typeof cfg === 'object'
+            ? code == null
+                ? 'error'
+                : resolveUniformSeverity(cfg[code], null)
+            : resolveUniformSeverity(cfg, code == null ? 'error' : null);
+        if (severity == null) {
             return null;
         }
-        let severity;
-        if (typeof cfg === 'object') {
-            if (code == null) {
-                // Fatal ParserError without a code; the Record form cannot target
-                // it, so fall back to `'error'` (the channel is otherwise enabled).
-                severity = 'error';
-            }
-            else {
-                const perCode = cfg[code];
-                if (perCode == null || perCode === false || perCode === 'off') {
-                    return null;
-                }
-                severity = perCode === true ? 'error' : perCode;
-            }
-        }
-        else if (cfg == null) {
-            // New default: non-fatal `parseErrors` entries are off; fatal
-            // `ParserError`s (no code) still emit at `'error'`.
-            if (code != null) {
-                return null;
-            }
-            severity = 'error';
-        }
-        else {
-            // Uniform string/boolean form (legacy).
-            severity = cfg === true ? 'error' : cfg;
-        }
         return {
             ruleId: 'parse-error',
             severity,
@@ -597,6 +631,24 @@ export class MLCore {
         }
     }
 }
+/**
+ * Normalizes a single-value `Severity | 'off' | boolean | undefined` option
+ * (the shape `severity.deprecation` and `severity.parseError`'s uniform/
+ * per-code leaf values share) to a resolved severity or `null` (suppressed).
+ *
+ * Shared so the same three-way rule — `false`/`'off'` → suppressed, `true` →
+ * `'error'`, unset → `defaultWhenUnset` — isn't reimplemented at each call
+ * site as channels using this shape are added.
+ */
+function resolveUniformSeverity(cfg, defaultWhenUnset) {
+    if (cfg === false || cfg === 'off') {
+        return null;
+    }
+    if (cfg == null) {
+        return defaultWhenUnset;
+    }
+    return cfg === true ? 'error' : cfg;
+}
 function extractDisabledNamespaces(rules) {
     return Object.entries(rules)
         .filter(([key, value]) => key.endsWith('/*') && value === false)

package/lib/types.d.ts

@@ -2,7 +2,7 @@ import type { AnyMLRule } from './ml-rule/index.js';
 import type { Ruleset } from './ruleset/index.js';
 import type { LocaleSet } from '@markuplint/i18n';
 import type { MLParser, ParserOptions } from '@markuplint/ml-ast';
-import type { Pretender, RuleCommonSettings, SeverityOptions } from '@markuplint/ml-config';
+import type { Pretender, RuleAliasWarning, RuleCommonSettings, SeverityOptions } from '@markuplint/ml-config';
 import type { ExtendedSpec, MLMLSpec } from '@markuplint/ml-spec';
 /**
  * A tuple of the base HTML/ARIA specification and zero or more
@@ -24,4 +24,11 @@ export type MLFabric = {
     readonly severity: SeverityOptions;
     readonly pretenders: readonly Pretender[];
     readonly configErrors?: readonly Readonly<Error>[];
+    /**
+     * Deprecated-rule-name notices found while applying the rule-alias table
+     * (v5 rule-system redesign, #3989). Kept structured, separate from
+     * {@link configErrors}, so `MLCore.verify()` can report them under their
+     * own `rule-deprecation` ruleId instead of `config-error`.
+     */
+    readonly ruleDeprecations?: readonly RuleAliasWarning[];
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@markuplint/ml-core",
-	"version": "5.0.0-rc.5",
+	"version": "5.0.0-rc.6",
 	"description": "The core module of markuplint",
 	"repository": {
 		"type": "git",
@@ -34,20 +34,20 @@
 		"./lib/configs.js": "./lib/configs.browser.js"
 	},
 	"dependencies": {
-		"@markuplint/config-presets": "5.0.0-rc.5",
-		"@markuplint/html-parser": "5.0.0-rc.5",
-		"@markuplint/html-spec": "5.0.0-rc.5",
-		"@markuplint/i18n": "5.0.0-rc.5",
-		"@markuplint/ml-ast": "5.0.0-rc.5",
-		"@markuplint/ml-config": "5.0.0-rc.5",
-		"@markuplint/ml-spec": "5.0.0-rc.5",
-		"@markuplint/parser-utils": "5.0.0-rc.5",
-		"@markuplint/selector": "5.0.0-rc.5",
-		"@markuplint/shared": "5.0.0-rc.5",
+		"@markuplint/config-presets": "5.0.0-rc.6",
+		"@markuplint/html-parser": "5.0.0-rc.6",
+		"@markuplint/html-spec": "5.0.0-rc.6",
+		"@markuplint/i18n": "5.0.0-rc.6",
+		"@markuplint/ml-ast": "5.0.0-rc.6",
+		"@markuplint/ml-config": "5.0.0-rc.6",
+		"@markuplint/ml-spec": "5.0.0-rc.6",
+		"@markuplint/parser-utils": "5.0.0-rc.6",
+		"@markuplint/selector": "5.0.0-rc.6",
+		"@markuplint/shared": "5.0.0-rc.6",
 		"@types/debug": "4.1.13",
 		"debug": "4.4.3",
 		"is-plain-object": "5.0.0",
 		"type-fest": "5.6.0"
 	},
-	"gitHead": "8d87463af2ff3f1b83fb28da20f1819362cf3555"
+	"gitHead": "c02c3a0783eac6b2fb4707be2dc00b88f6219641"
 }