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

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.
  *
@@ -24,7 +38,24 @@ 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;
+    /**
+     * 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
+     * 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,12 +64,8 @@ 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, }) {
+    constructor({ parser, sourceCode, ruleset, rules, locale, schemas, ruleCommonSettings, parserOptions, severity, pretenders, filename, debug, configErrors, ruleDeprecations, }) {
         if (debug) {
             enableDebug();
         }
@@ -52,12 +79,11 @@ 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 ?? [];
-        // 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 +123,21 @@ 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, 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);
-        // 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,20 +176,24 @@ 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({
-                    ruleId: 'config-error',
+                configViolations.push({
+                    ruleId: CONFIG_ERROR_RULE_ID,
                     severity: 'warning',
                     message: `Rule not found: ${setRuleName}`,
                     col: 1,
@@ -173,9 +202,9 @@ export class MLCore {
                 });
             }
         }
-        for (const error of this.#configErrors) {
-            violations.push({
-                ruleId: 'config-error',
+        for (const error of [...this.#configErrors, ...this.#mappingErrors]) {
+            configViolations.push({
+                ruleId: CONFIG_ERROR_RULE_ID,
                 severity: 'warning',
                 message: error.message,
                 col: 1,
@@ -183,6 +212,20 @@ 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);
         if (resultLog.enabled) {
@@ -200,7 +243,6 @@ export class MLCore {
             resultLog('Warning: %d', w);
             resultLog('Info: %d', i);
         }
-        // Apply fixes if enabled
         let fixedCode;
         let fixSummary;
         if (fix) {
@@ -209,16 +251,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 +290,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 +305,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 +321,126 @@ 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);
+            }
+        }
+    }
+    /**
+     * 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`.
+     *
+     * 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;
+        // 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;
         }
-        // Default severity is 'error'
-        const severity = this.#severity.parseError === true || this.#severity.parseError == null
-            ? 'error'
-            : this.#severity.parseError;
         return {
             ruleId: 'parse-error',
             severity,
@@ -278,23 +451,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 +491,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 +537,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 +568,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) {
@@ -425,16 +632,29 @@ export class MLCore {
     }
 }
 /**
- * Extracts namespace prefixes from wildcard disable entries in rules.
- * e.g., `{ "a11y/*": false }` yields `["a11y/"]`.
+ * 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)
         .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 +676,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;

package/lib/ml-dom/helper/accname.js

@@ -1,14 +1,6 @@
 import { computeAccessibleName, escapeCSS, getComputedRole, EMBEDDED_CONTROL_ROLES, isNativeEmbeddedControl, } from '@markuplint/ml-spec';
 import { log } from '../../debug.js';
 const accnameLog = log.extend('accname');
-/**
- * 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 function getAccname(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, version) {
@@ -18,8 +10,13 @@ el, version) {
     // environment differences (e.g., Deno lacking certain DOM APIs).
     // A single element's failure must not abort the entire linting process,
     // so we catch all errors and return an empty name (= "unnamed").
-    // This is an intentional exception to the Tier 1 re-throw policy — see
-    // docs/architectures/ERROR-HANDLING.md § "accname computation errors".
+    // This is an intentional exception to the Tier 1 re-throw policy (see
+    // `isFatalError()` in `@markuplint/shared`): Tier-1-shaped errors here
+    // can be caused by the runtime environment, not only implementation bugs.
+    // The empty-string result is not converted to a violation either — a
+    // single element's accname failure must not create noise across
+    // unrelated rules, and "unnamed" still drives meaningful a11y rule
+    // violations downstream.
     try {
         const resolver = createMLCoreResolver(el, version);
         const result = computeAccessibleName(el, resolver);

package/lib/ml-dom/node/attr.js

@@ -131,7 +131,9 @@ export class MLAttr extends MLNode {
                 this.isDirective = this._astToken.isDirective;
                 this.isDuplicatable = this._astToken.isDuplicatable;
             }
-            // IDL attribute resolution (after directivePatterns)
+            // IDL attribute resolution (after directivePatterns).
+            // Performed in the core, not in each parser: any spec opting in via
+            // `acceptedAttrNames` shares the same IDL-to-content-attribute mapping.
             if (ownElement.ownerMLDocument.specs.acceptedAttrNames && !this.isDirective) {
                 const { contentAttrName, idlPropName } = searchIDLAttribute(this.#potentialName);
                 if (contentAttrName && contentAttrName !== this.#potentialName) {

package/lib/ml-dom/node/block.d.ts

@@ -9,6 +9,12 @@ import { MLNode } from './node.js';
  * These nodes correspond to template engine constructs such as conditionals (`if`/`else`),
  * loops (`each`), and other preprocessor directives that are not part of standard HTML.
  *
+ * Serves as the bridge between template syntax and HTML content model
+ * validation: transparency keeps the wrapper invisible to DOM traversal so
+ * rules such as `permitted-contents` see the effective HTML children, while
+ * `blockBehavior` lets `conditionalChildNodes()` enumerate every possible
+ * rendering branch.
+ *
  * @template T - The rule configuration value type
  * @template O - The rule options type
  */

package/lib/ml-dom/node/block.js

@@ -5,6 +5,12 @@ import { MLNode } from './node.js';
  * These nodes correspond to template engine constructs such as conditionals (`if`/`else`),
  * loops (`each`), and other preprocessor directives that are not part of standard HTML.
  *
+ * Serves as the bridge between template syntax and HTML content model
+ * validation: transparency keeps the wrapper invisible to DOM traversal so
+ * rules such as `permitted-contents` see the effective HTML children, while
+ * `blockBehavior` lets `conditionalChildNodes()` enumerate every possible
+ * rendering branch.
+ *
  * @template T - The rule configuration value type
  * @template O - The rule options type
  */

package/lib/ml-dom/node/child-node.d.ts

@@ -15,13 +15,4 @@ import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
  * @see https://dom.spec.whatwg.org/#idl-index
  */
 export type MLChildNode<T extends RuleConfigValue, O extends PlainData = undefined> = MLDocumentType<T, O> | MLCharacterData<T, O> | MLElement<T, O> | MLBlock<T, O>;
-/**
- * Determines whether the given node is a child node type
- * (DocumentType, CDATA, Comment, Text, Element, or preprocessor block).
- *
- * @template T - The rule configuration value type
- * @template O - The rule options type
- * @param node - The node to check
- * @returns True if the node is one of the child node types
- */
 export declare function isChildNode<T extends RuleConfigValue, O extends PlainData = undefined>(node: MLNode<T, O>): node is MLChildNode<T, O>;

package/lib/ml-dom/node/child-node.js

@@ -1,12 +1,3 @@
-/**
- * Determines whether the given node is a child node type
- * (DocumentType, CDATA, Comment, Text, Element, or preprocessor block).
- *
- * @template T - The rule configuration value type
- * @template O - The rule options type
- * @param node - The node to check
- * @returns True if the node is one of the child node types
- */
 export function isChildNode(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node) {