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

package/CHANGELOG.md

@@ -3,6 +3,43 @@
 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.5](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.4...v5.0.0-rc.5) (2026-08-28)
+
+### Bug Fixes
+
+- **ml-core:** look up dedupe contract under both alias and base rule names ([a5dde7e](https://github.com/markuplint/markuplint/commit/a5dde7e23a12a43d976fbfaa1cc3dec67265447e)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844) [#3871](https://github.com/markuplint/markuplint/issues/3871)
+- **ml-core:** re-verify fixed code and detect N-pass fix cycles ([8c96516](https://github.com/markuplint/markuplint/commit/8c96516d8057acdcf06dc279c2183390f0966e98)), closes [#3890](https://github.com/markuplint/markuplint/issues/3890) [#3891](https://github.com/markuplint/markuplint/issues/3891)
+- **ml-core:** stop accumulating duplicate mapping errors across setCode ([2874d5b](https://github.com/markuplint/markuplint/commit/2874d5b60b24ccc501f7dae1f6ab25fb6e51e58b)), closes [#3900](https://github.com/markuplint/markuplint/issues/3900)
+- **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))
+
+### 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)
+
+- fix(ml-core)!: reject pretender on standard HTML elements ([0576425](https://github.com/markuplint/markuplint/commit/0576425baf9b78141523bcd0e4a102062b96bc81)), closes [#3740](https://github.com/markuplint/markuplint/issues/3740)
+
+### Features
+
+- **ml-core:** hook-based dedupe for parse-error channel via mirrorsParseErrorCodes ([6a36f17](https://github.com/markuplint/markuplint/commit/6a36f17d292a2400494a3670c93cb2f02999b48b)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844)
+- **ml-core:** surface non-fatal parser errors via opt-in parse-error channel ([d715fbe](https://github.com/markuplint/markuplint/commit/d715fbe586c478b98472a570b3175873cf244aef)), closes [#3844](https://github.com/markuplint/markuplint/issues/3844)
+
+### BREAKING CHANGES
+
+- **rules:** with no alias coverage.
+- `pretenders` config entries whose selector matches a
+  standard HTML element are now ignored. Configurations that previously
+  relied on `<marquee as="div">` to suppress markuplint violations must
+  remove the entry; the original element is now linted on its own merits.
+
+# [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/ml-core
+
+# [5.0.0-rc.3](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.2...v5.0.0-rc.3) (2026-04-19)
+
+**Note:** Version bump only for package @markuplint/ml-core
+
 # [5.0.0-rc.2](https://github.com/markuplint/markuplint/compare/v5.0.0-rc.1...v5.0.0-rc.2) (2026-04-15)
 
 ### Bug Fixes

package/README.md

@@ -5,11 +5,6 @@
 ## Documentation
 
 - [API Document](https://markuplint.dev/api-docs)
-- [Architecture](ARCHITECTURE.md) ([日本語](ARCHITECTURE.ja.md)) — Package overview, MLDOM hierarchy, rule system, and linting pipeline
-- [MLDOM Reference](docs/ml-dom.md) ([日本語](docs/ml-dom.ja.md)) — Class hierarchy, node properties, tree traversal
-- [Rule System](docs/rule-system.md) ([日本語](docs/rule-system.ja.md)) — MLRule, RuleSeed, MLRuleContext, configuration resolution
-- [Linting Pipeline](docs/linting-pipeline.md) ([日本語](docs/linting-pipeline.ja.md)) — MLCore engine, verify flow, pretender, plugin system
-- [Maintenance Guide](docs/maintenance.md) ([日本語](docs/maintenance.ja.md)) — Commands, recipes, and troubleshooting
 
 ## Install
 

package/lib/cursor-offset.js

@@ -15,16 +15,13 @@ export function computeCursorOffset(appliedEdits, cursorOffset) {
         const [start, end] = edit.range;
         const delta = edit.text.length - (end - start);
         if (start > cursorOffset) {
-            // Edit is after cursor — no effect
             break;
         }
         if (end <= cursorOffset) {
-            // Edit is entirely before cursor — shift by delta.
             // Range is half-open [start, end), so cursor at `end` is outside the edit.
             newOffset += delta;
         }
         else {
-            // Cursor falls inside the replaced range [start, end)
             newOffset = start + edit.text.length;
             break;
         }

package/lib/fix-applier.js

@@ -19,20 +19,18 @@ export function applyFixes(sourceCode, fixes) {
     if (fixes.length === 0) {
         return { output: sourceCode, applied: [], skipped: [], appliedEdits: [] };
     }
-    // Tag each edit with its parent FixData index
     const taggedEdits = [];
     for (const [i, fix] of fixes.entries()) {
         for (const edit of fix.edits) {
             taggedEdits.push({ edit, fixIndex: i });
         }
     }
-    // Sort: range[0] ascending, then range[1] descending (so larger ranges come first at the same start)
+    // Ties broken by range[1] descending so larger ranges come first at the same start.
     taggedEdits.sort((a, b) => {
         const startDiff = a.edit.range[0] - b.edit.range[0];
         // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
         return startDiff || b.edit.range[1] - a.edit.range[1];
     });
-    // Track which FixData indices had at least one skipped edit
     const skippedFixIndices = new Set();
     const appliedEdits = [];
     let lastAppliedEnd = -1;
@@ -40,22 +38,18 @@ export function applyFixes(sourceCode, fixes) {
     let cursor = 0;
     for (const { edit, fixIndex } of taggedEdits) {
         const [start, end] = edit.range;
-        // Overlap check: if this edit starts before the end of the last applied edit, skip it.
-        // Also skip if a sibling edit from the same FixData was already skipped —
-        // edits within a single FixData are atomic (all-or-nothing).
+        // Edits within a single FixData are atomic (all-or-nothing): if any sibling
+        // was skipped, skip the rest.
         if (start < lastAppliedEnd || skippedFixIndices.has(fixIndex)) {
             skippedFixIndices.add(fixIndex);
             continue;
         }
-        // Append the source text between the last edit and this one
         parts.push(sourceCode.slice(cursor, start), edit.text);
         appliedEdits.push(edit);
         cursor = end;
         lastAppliedEnd = end;
     }
-    // Append remaining source text
     parts.push(sourceCode.slice(cursor));
-    // Classify FixData as applied or skipped
     const applied = [];
     const skipped = [];
     for (const [i, fix] of fixes.entries()) {

package/lib/ml-core.d.ts

@@ -22,6 +22,20 @@ export type FixSummary = {
      * multiple passes are executed.
      */
     readonly firstPassEdits: readonly TextEdit[];
+    /**
+     * Violations remaining in the final fixed code, re-verified after the
+     * last fix pass.
+     *
+     * Unlike {@link VerifyResult.violations} (which reflects the first pass
+     * only), this list is accurate for `fixedCode`. Callers that report
+     * post-fix results should prefer `fixSummary.finalPassViolations ?? violations`.
+     * Entries may carry `fix` data whose offsets refer to `fixedCode`.
+     *
+     * `undefined` when no fixes remain applied (none were applied, or the
+     * applied pass was rolled back); the first-pass violations are then
+     * accurate as-is.
+     */
+    readonly finalPassViolations?: readonly Violation[];
 };
 /**
  * Options for {@link MLCore.verify}.
@@ -77,7 +91,7 @@ export declare class MLCore {
      *
      * @param fabric - Partial fabric with the properties to update
      */
-    update({ parser, ruleset, rules, locale, schemas, parserOptions, configErrors }: Partial<MLFabric>): void;
+    update({ parser, ruleset, rules, locale, schemas, parserOptions, pretenders, configErrors }: Partial<MLFabric>): void;
     /**
      * Runs all configured rules against the parsed document and returns violations.
      *
@@ -91,7 +105,9 @@ export declare class MLCore {
      * may be the result of multiple fix passes. This means some violations in the
      * array may already be resolved in `fixedCode`, and new violations introduced
      * during later passes are not included in the array. Callers needing an accurate
-     * violation list for the fixed code should re-verify the output.
+     * violation list for the fixed code should use `fixSummary.finalPassViolations`,
+     * which is re-verified against the final code whenever at least one fix was
+     * applied.
      *
      * @param fixOrOptions - Whether to attempt auto-fixing violations, or an options object
      * @returns Violations from the initial analysis and the (possibly fixed) source code

package/lib/ml-core.js

@@ -24,7 +24,17 @@ export class MLCore {
     #schemas;
     #ruleCommonSettings;
     #sourceCode;
+    /**
+     * Config-time errors (named-rule expansion, the `configErrors` fabric input).
+     * Set once per construction/`update()` and never mutated by re-parsing.
+     */
     #configErrors;
+    /**
+     * Rule-mapping errors for the CURRENT document. Reset (not accumulated) on
+     * every `#createDocument()` so repeated `setCode()` calls don't duplicate
+     * them. See https://github.com/markuplint/markuplint/issues/3900.
+     */
+    #mappingErrors = [];
     /**
      * Pre-expansion nodeRules preserved for hot-reload.
      * When `update()` is called without a new ruleset, these are used as the
@@ -33,10 +43,6 @@ export class MLCore {
      */
     #originalNodeRules;
     #originalChildNodeRules;
-    /**
-     * Pre-computed namespace prefixes from wildcard disable entries.
-     * e.g., `rules["a11y/*"]: false` yields `"a11y/"`.
-     */
     #disabledNamespaces;
     constructor({ parser, sourceCode, ruleset, rules, locale, schemas, ruleCommonSettings, parserOptions, severity, pretenders, filename, debug, configErrors, }) {
         if (debug) {
@@ -55,9 +61,7 @@ export class MLCore {
         // Preserve pre-expansion nodeRules for hot-reload
         this.#originalNodeRules = ruleset.nodeRules ?? [];
         this.#originalChildNodeRules = ruleset.childNodeRules ?? [];
-        // Expand named rule groups in the rules section
         const namedRulesResult = expandNamedRules(ruleset.rules ?? {}, rules);
-        // Expand named nodeRules into virtual rules (using expanded rules as base)
         const allRulesForExpansion = [...rules, ...namedRulesResult.virtualRules];
         const nodeRuleResult = expandNamedNodeRules(this.#originalNodeRules, allRulesForExpansion);
         const childNodeRuleResult = expandNamedNodeRules(this.#originalChildNodeRules, allRulesForExpansion);
@@ -97,22 +101,20 @@ export class MLCore {
      *
      * @param fabric - Partial fabric with the properties to update
      */
-    update({ parser, ruleset, rules, locale, schemas, parserOptions, configErrors }) {
+    update({ parser, ruleset, rules, locale, schemas, parserOptions, pretenders, configErrors }) {
         this.#parser = parser ?? this.#parser;
         this.#locale = locale ?? this.#locale;
         this.#schemas = schemas ?? this.#schemas;
+        this.#pretenders = pretenders ? [...pretenders] : this.#pretenders;
         this.#configErrors = [...(configErrors ?? [])];
         const baseRules = rules ? [...rules] : this.#rules.filter(r => !r.baseRuleId);
-        // Use pre-expansion originals as fallback when ruleset is not provided
         const incomingNodeRules = ruleset?.nodeRules ?? this.#originalNodeRules;
         const incomingChildNodeRules = ruleset?.childNodeRules ?? this.#originalChildNodeRules;
-        // Expand named rule groups in the rules section
         const incomingRules = ruleset?.rules ?? this.#ruleset.rules;
         const namedRulesResult = expandNamedRules(incomingRules, baseRules);
         const allRulesForExpansion = [...baseRules, ...namedRulesResult.virtualRules];
         const nodeRuleResult = expandNamedNodeRules(incomingNodeRules, allRulesForExpansion);
         const childNodeRuleResult = expandNamedNodeRules(incomingChildNodeRules, allRulesForExpansion);
-        // Update originals if new data was provided
         if (ruleset?.nodeRules) {
             this.#originalNodeRules = ruleset.nodeRules;
         }
@@ -151,19 +153,23 @@ export class MLCore {
             log('verify: error %o', this.#document.message);
             return { violations, fixedCode: fix ? this.#sourceCode : undefined };
         }
+        this.#pushNonFatalParseErrors(violations);
         const definedRuleName = new Set(this.#rules.map(rule => rule.name));
         const setRuleNames = new Set([
             ...Object.keys(this.#ruleset.rules),
             ...this.#ruleset.nodeRules.flatMap(nodeRule => Object.keys(nodeRule.rules ?? {})),
             ...this.#ruleset.childNodeRules.flatMap(childNodeRule => Object.keys(childNodeRule.rules ?? {})),
         ]);
+        // Config-level violations are independent of the source code, so they are
+        // collected separately to also be included in `finalPassViolations`.
+        const configViolations = [];
         for (const setRuleName of setRuleNames) {
             // Skip wildcard patterns (e.g., "a11y/*") — they are namespace disable entries, not rule references
             if (setRuleName.endsWith('/*')) {
                 continue;
             }
             if (!definedRuleName.has(setRuleName)) {
-                violations.push({
+                configViolations.push({
                     ruleId: 'config-error',
                     severity: 'warning',
                     message: `Rule not found: ${setRuleName}`,
@@ -173,8 +179,8 @@ export class MLCore {
                 });
             }
         }
-        for (const error of this.#configErrors) {
-            violations.push({
+        for (const error of [...this.#configErrors, ...this.#mappingErrors]) {
+            configViolations.push({
                 ruleId: 'config-error',
                 severity: 'warning',
                 message: error.message,
@@ -183,6 +189,7 @@ export class MLCore {
                 raw: '',
             });
         }
+        violations.push(...configViolations);
         const ruleViolations = await this.#runAllRules(fix);
         violations.push(...ruleViolations);
         if (resultLog.enabled) {
@@ -200,7 +207,6 @@ export class MLCore {
             resultLog('Warning: %d', w);
             resultLog('Info: %d', i);
         }
-        // Apply fixes if enabled
         let fixedCode;
         let fixSummary;
         if (fix) {
@@ -209,16 +215,28 @@ export class MLCore {
                 const originalSourceCode = this.#sourceCode;
                 const originalAst = this.#ast;
                 const originalDocument = this.#document;
+                const originalMappingErrors = this.#mappingErrors;
                 try {
                     const fixResult = await this.#multiPassFix(violations);
                     fixedCode = fixResult.code;
                     fixSummary = fixResult.summary;
+                    if (configViolations.length > 0 && fixSummary.finalPassViolations) {
+                        // Config-level violations persist regardless of fixing;
+                        // keep them visible in the post-fix violation list.
+                        fixSummary = {
+                            ...fixSummary,
+                            finalPassViolations: [...configViolations, ...fixSummary.finalPassViolations],
+                        };
+                    }
                 }
                 finally {
-                    // Restore original state - verify() must be non-mutating
+                    // Restore original state - verify() must be non-mutating.
+                    // The fix loop re-parses, and each #createDocument resets
+                    // #mappingErrors; restore it to the pre-fix document's.
                     this.#sourceCode = originalSourceCode;
                     this.#ast = originalAst;
                     this.#document = originalDocument;
+                    this.#mappingErrors = originalMappingErrors;
                 }
             }
             else {
@@ -236,6 +254,10 @@ export class MLCore {
         return { violations, fixedCode, fixSummary };
     }
     #createDocument() {
+        // Reset up front: mapping errors belong to the document being (re)built,
+        // so a failed parse or build must not leave a previous document's errors
+        // behind. Repopulated below only on a successful build. See #3900.
+        this.#mappingErrors = [];
         if (!this.#ast) {
             return;
         }
@@ -247,8 +269,11 @@ export class MLCore {
                 tagNameCaseSensitive: this.#parser.tagNameCaseSensitive,
                 pretenders: this.#pretenders,
             });
-            // Collect errors from rule mapping (e.g., invalid wildcard usage)
-            this.#configErrors.push(...this.#ruleset.mappingErrors);
+            // Collect errors from rule mapping (e.g., invalid wildcard usage).
+            // Reset rather than append: the Document constructor regenerates
+            // `mappingErrors` on every call, so accumulating them would duplicate
+            // the same errors on each re-parse (e.g. via setCode). See #3900.
+            this.#mappingErrors = [...this.#ruleset.mappingErrors];
             this.#ruleset.mappingErrors.length = 0;
         }
         catch (error) {
@@ -260,14 +285,128 @@ export class MLCore {
             }
         }
     }
-    #createParseError(message, line, col, raw) {
-        if (this.#severity.parseError === false || this.#severity.parseError === 'off') {
+    /**
+     * Surfaces non-fatal parser conformance errors collected by the underlying
+     * parser (e.g., parse5's `onParseError` events on `MLASTDocument.parseErrors`)
+     * via the same `parse-error` violation channel as fatal `ParserError`s.
+     *
+     * Order contract (relied on by every rule spec under
+     * `@markuplint/rules/src/**`): each `parseErrors` entry is pushed in the
+     * order the parser emitted it, *before* any rule iteration runs. Tests
+     * that match on `toStrictEqual([...])` depend on this position.
+     *
+     * Severity resolution:
+     *
+     * - `severity.parseError` is a `Partial<Record<MLASTParseErrorCode, …>>` →
+     *   each entry's `code` looks up its own severity; codes absent from the
+     *   record default to `'off'` (suppressed).
+     * - `severity.parseError` is a single severity string/boolean → applied
+     *   uniformly to every entry.
+     * - `severity.parseError` is unset → **all non-fatal codes are off**.
+     *   Users must opt in explicitly.
+     *
+     * @param violations The verify-time violations array to mutate.
+     */
+    #pushNonFatalParseErrors(violations) {
+        const parseErrors = this.#ast?.parseErrors;
+        if (!parseErrors) {
+            return;
+        }
+        // Build the Set of parse5 codes that an active ml rule has claimed
+        // responsibility for via `meta.mirrorsParseErrorCodes`. The user's
+        // ruleset decides whether each rule's declaration is in scope:
+        //
+        // - Rule **set** in the ruleset (config !== undefined) — whatever the
+        //   value (`true`, `false`, severity, object) — the user has expressed
+        //   intent about this check. Honour the mirror declaration:
+        //   - active: the rule itself will report violations for those codes
+        //   - disabled (`false`): the user explicitly opted out, so the channel
+        //     stays silent too — no surprise re-surfacing
+        // - Rule **not mentioned** (config === undefined) — pure default. The
+        //   parse-error channel remains the channel of record for those codes
+        //   and surfaces them when the user has opted in via `severity.parseError`.
+        //
+        // This keeps the responsibility clean: rule packages declare what they
+        // cover (static metadata); ml-core honours the user's ruleset choice;
+        // no per-node logic, no hard-coded code→rule map.
+        const mirroredCodes = new Set();
+        for (const rule of this.#rules) {
+            if (rule.mirrorsParseErrorCodes.length === 0) {
+                continue;
+            }
+            // The rule is "mentioned in the ruleset" if **either** the alias
+            // name OR the base rule name has an entry. Two entry styles exist:
+            //
+            // - Direct user configs use base rule names: `rules.attr-duplication`
+            // - Preset named nodeRules use alias names: `rules['html-standard/attr-duplication']`
+            //
+            // `MLRule` for a preset-aliased entry has `rule.name = 'html-standard/...'`
+            // and `rule.baseRuleId = 'attr-duplication'`; for a direct entry,
+            // `rule.name = 'attr-duplication'` and `baseRuleId` is undefined.
+            // Checking both names covers both styles.
+            const aliasConfig = this.#ruleset.rules[rule.name];
+            const baseConfig = rule.baseRuleId === undefined ? undefined : this.#ruleset.rules[rule.baseRuleId];
+            if (aliasConfig === undefined && baseConfig === undefined) {
+                continue;
+            }
+            for (const code of rule.mirrorsParseErrorCodes) {
+                mirroredCodes.add(code);
+            }
+        }
+        for (const parserError of parseErrors) {
+            if (mirroredCodes.has(parserError.code)) {
+                continue;
+            }
+            const violation = this.#createParseError(`Parser conformance error: ${parserError.code}`, parserError.startLine, parserError.startCol, parserError.raw, parserError.code);
+            if (violation) {
+                violations.push(violation);
+            }
+        }
+    }
+    /**
+     * Builds a `ruleId: 'parse-error'` violation, honouring
+     * `severity.parseError`.
+     *
+     * If `code` is supplied (non-fatal `parseErrors` entry) and the option is
+     * a `Partial<Record<code, severity>>`, the per-code value is used (absent
+     * codes default to `'off'`). If the option is unset, non-fatal entries
+     * are suppressed (opt-in only) while fatal errors (no `code`) still
+     * default to `'error'`.
+     *
+     * @returns the violation, or `null` if suppressed.
+     */
+    #createParseError(message, line, col, raw, code) {
+        const cfg = this.#severity.parseError;
+        if (cfg === false || cfg === 'off') {
             return null;
         }
-        // Default severity is 'error'
-        const severity = this.#severity.parseError === true || this.#severity.parseError == null
-            ? 'error'
-            : this.#severity.parseError;
+        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,
@@ -278,23 +417,29 @@ export class MLCore {
         };
     }
     /**
-     * Iteratively applies fixes, re-parses, and re-verifies until no overlapping
-     * fixes remain or the maximum pass count is reached (ESLint-style multi-pass loop).
+     * ESLint-style multi-pass fix loop (modeled after SourceCodeFixer).
      *
      * **Callers must save/restore `#sourceCode`, `#ast`, and `#document`** because
      * this method mutates them during intermediate re-parse steps.
-     *
-     * @param initialViolations - Violations from the first verification pass
-     * @returns The final fixed source code and a summary of the fix process
      */
     async #multiPassFix(initialViolations) {
+        // Same safety cap as ESLint's SourceCodeFixer (10 passes).
         const MAX_FIX_PASSES = 10;
         let currentCode = this.#sourceCode;
-        let previousCode;
         let fixes = extractFixes(initialViolations);
         let totalApplied = 0;
         let totalSkipped = 0;
         let firstPassEdits = [];
+        // The input code of each pass, keyed by code string, for N-pass cycle
+        // detection (A → B → A as well as longer cycles such as A → B → C → A).
+        const codeHistory = new Map([[currentCode, 0]]);
+        // Violations from the latest #runAllRules call, valid for `currentCode`.
+        // Reused by the final verification below to avoid a redundant re-run
+        // when the loop already re-verified the final code.
+        let latestViolations;
+        // The most recent code that is known to parse successfully. Used to roll
+        // back a pass whose output fails to parse.
+        let lastParsableCode = currentCode;
         let pass = 0;
         for (; pass < MAX_FIX_PASSES; pass++) {
             log('fix pass %d: %d fixes', pass, fixes.length);
@@ -312,31 +457,42 @@ export class MLCore {
                 log('fix pass %d: output unchanged, stopping', pass);
                 break;
             }
-            // Cycle detection: if the output matches the code from two passes ago,
-            // fixes are oscillating (A → B → A) and will never converge.
-            if (previousCode !== undefined && result.output === previousCode) {
-                log('fix pass %d: cycle detected (output matches pass %d), stopping', pass, pass - 2);
+            // Cycle detection: if the output matches the input of any earlier pass,
+            // fixes are oscillating (A → B → A, A → B → C → A, ...) and will never converge.
+            const cycleStart = codeHistory.get(result.output);
+            if (cycleStart !== undefined) {
+                log('fix pass %d: cycle detected (output matches the input of pass %d, cycle length %d), stopping', pass, cycleStart, pass + 1 - cycleStart);
                 currentCode = result.output;
+                latestViolations = undefined;
                 break;
             }
-            previousCode = currentCode;
             currentCode = result.output;
-            if (result.skipped.length === 0) {
-                log('fix pass %d: all fixes applied, stopping', pass);
-                break;
-            }
-            // --- Multi-pass path (only when overlapping fixes exist) ---
-            log('fix pass %d: %d skipped, re-parsing for next pass', pass, result.skipped.length);
-            const previousGoodCode = currentCode;
+            codeHistory.set(currentCode, pass + 1);
+            latestViolations = undefined;
+            // Parse the output immediately — for the next pass or for the final
+            // verification — so an unparsable output is always rolled back
+            // instead of being returned (and written to disk) broken.
             this.#sourceCode = currentCode;
             this.#parse();
             this.#createDocument();
             if (this.#document instanceof ParserError) {
-                log('fix pass %d: produced unparsable code, reverting to previous state', pass);
-                currentCode = previousGoodCode;
+                log('fix pass %d: produced unparsable code, reverting to the previous parsable code', pass);
+                currentCode = lastParsableCode;
+                totalApplied -= result.applied.length;
+                if (pass === 0) {
+                    firstPassEdits = [];
+                }
+                break;
+            }
+            lastParsableCode = currentCode;
+            if (result.skipped.length === 0) {
+                log('fix pass %d: all fixes applied, stopping', pass);
                 break;
             }
+            // --- Multi-pass path (only when overlapping fixes exist) ---
+            log('fix pass %d: %d skipped, re-running rules for next pass', pass, result.skipped.length);
             const newViolations = await this.#runAllRules(true);
+            latestViolations = newViolations;
             fixes = extractFixes(newViolations);
             if (fixes.length === 0) {
                 log('fix pass %d: no more fixable violations, stopping', pass);
@@ -347,6 +503,29 @@ export class MLCore {
         if (reachedMaxPasses) {
             log('fix: reached maximum number of passes (%d), some fixes may not have been applied', MAX_FIX_PASSES);
         }
+        // Final verification (#3890): compute the violations that remain in the
+        // final code. When the loop already re-verified `currentCode`, reuse that
+        // result; otherwise re-run rules once (re-parsing first unless the parsed
+        // state already corresponds to `currentCode`).
+        let finalPassViolations;
+        if (totalApplied > 0) {
+            if (latestViolations === undefined) {
+                if (this.#sourceCode !== currentCode) {
+                    this.#sourceCode = currentCode;
+                    this.#parse();
+                    this.#createDocument();
+                }
+                if (!(this.#document instanceof ParserError)) {
+                    latestViolations = await this.#runAllRules(true);
+                }
+            }
+            if (latestViolations !== undefined) {
+                const collected = [];
+                this.#pushNonFatalParseErrors(collected);
+                collected.push(...latestViolations);
+                finalPassViolations = collected;
+            }
+        }
         return {
             code: currentCode,
             summary: {
@@ -355,16 +534,10 @@ export class MLCore {
                 totalSkipped,
                 reachedMaxPasses,
                 firstPassEdits,
+                finalPassViolations,
             },
         };
     }
-    /**
-     * Executes all configured rules against the current document and collects violations.
-     * Skips disabled rules and handles virtual rule disable conditions.
-     *
-     * @param fix - Whether to execute fix callbacks on violations
-     * @returns All violations produced by the rule set
-     */
     async #runAllRules(fix) {
         const violations = [];
         if (this.#document instanceof ParserError) {
@@ -424,17 +597,12 @@ export class MLCore {
         }
     }
 }
-/**
- * Extracts namespace prefixes from wildcard disable entries in rules.
- * e.g., `{ "a11y/*": false }` yields `["a11y/"]`.
- */
 function extractDisabledNamespaces(rules) {
     return Object.entries(rules)
         .filter(([key, value]) => key.endsWith('/*') && value === false)
         .map(([key]) => key.slice(0, -1)); // "a11y/*" → "a11y/"
 }
 /**
- * Builds a mapping from base rule names to virtual rule names.
  * Used by nodeRules/childNodeRules to propagate settings (especially `false`)
  * to virtual rules created by NamedRuleGroups.
  */
@@ -456,12 +624,6 @@ virtualRules) {
     }
     return map;
 }
-/**
- * Collects all `FixData` from violations that have a fix callback result.
- *
- * @param violations - The violations to extract fixes from
- * @returns An array of `FixData` objects ready for `applyFixes()`
- */
 function extractFixes(violations) {
     const fixes = [];
     for (const v of violations) {

package/lib/ml-dom/helper/accname.d.ts

@@ -1,11 +1,3 @@
 import type { MLElement } from '../node/element.js';
 import type { ARIAVersion } from '@markuplint/ml-spec';
-/**
- * Computes the accessible name for an MLElement using the HTML-AAM algorithm.
- * Creates an MLCore-specific resolver that bridges MLElement to the AccnameResolver interface.
- *
- * @param el - The MLElement to compute the accessible name for
- * @param version - The ARIA specification version to use for role resolution
- * @returns The computed accessible name string, or an empty string on error
- */
 export declare function getAccname(el: MLElement<any, any>, version: ARIAVersion): string;