@markuplint/ml-core 5.1.1 → 5.3.0

package/CHANGELOG.md

@@ -3,6 +3,41 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.3.0](https://github.com/markuplint/markuplint/compare/v5.2.0...v5.3.0) (2026-10-21)
+
+### Bug Fixes
+
+* make published packages loadable from require() and put types first ([723106f](https://github.com/markuplint/markuplint/commit/723106f51aac4e60dc02db2c1a894617368b0253)), closes [#4198](https://github.com/markuplint/markuplint/issues/4198)
+* **ml-core:** add MLElement.isCustomElement so :model() matches #custom ([befdf3b](https://github.com/markuplint/markuplint/commit/befdf3be6623331b4fc5dca773df6ba745ea10ee)), closes [#custom](https://github.com/markuplint/markuplint/issues/custom)
+* **ml-core:** decide by the name that the DOM gives an attribute ([68f732c](https://github.com/markuplint/markuplint/commit/68f732ce3eec1203fbed479af1f1488e5f272a47))
+* **ml-core:** make the type selector and the pretender guard read `isNativeTag` of the parser ([9f7877f](https://github.com/markuplint/markuplint/commit/9f7877f10a02d86e5efe5254b414ef232f08c2a6))
+* **ml-core:** match attribute names case-insensitively in getAttributeToken ([418e627](https://github.com/markuplint/markuplint/commit/418e627d6f7402136654ed6f1007b06ad6da3d86)), closes [#4180](https://github.com/markuplint/markuplint/issues/4180)
+* **ml-core:** read a prefixed name as the HTML parser does and match Vue props by either spelling ([fe6cd8f](https://github.com/markuplint/markuplint/commit/fe6cd8f949fd28212e2123e4129c8dc3d7b0404f))
+* **ml-core:** tell the selector whether the document tells the case of a tag name apart ([f0a9c17](https://github.com/markuplint/markuplint/commit/f0a9c1783bd237f307647f0b3cb978edeb814037))
+* **ml-core:** treat a pretender target that is a component name as a component ([f20dc1b](https://github.com/markuplint/markuplint/commit/f20dc1be225e2f2e90f2c721bc2c10e8847b9809))
+* **rules:** compare attribute names as the DOM does in the rules that list attributes ([51faee6](https://github.com/markuplint/markuplint/commit/51faee6f13a8f09f136438873991f0581071012a))
+* **selector:** match a prefixed attribute by its local name as well ([a9beb11](https://github.com/markuplint/markuplint/commit/a9beb112b87bf9ade372ede0fe0d7958d05027fc))
+
+### Features
+
+* **ml-core:** ask whether a name is a prefix of an attribute, and keep suggesting the property ([bd195ef](https://github.com/markuplint/markuplint/commit/bd195ef6ededb80482c642a86360c5f932f8b91b))
+* **ml-core:** expose attrNameCaseSensitive on MLDocument ([d73a2fd](https://github.com/markuplint/markuplint/commit/d73a2fdc337425e6203da696abe785172f7b277d)), closes [#4229](https://github.com/markuplint/markuplint/issues/4229)
+* **ml-core:** read the parser's name rules through the document ([b4f03ea](https://github.com/markuplint/markuplint/commit/b4f03eaff13f52421993bbec490330a4039ee850)), closes [MLElement#tagNameKind](https://github.com/MLElement/issues/tagNameKind)
+* **parser-utils:** let a parser say how an attribute name gets into the DOM ([abd81e5](https://github.com/markuplint/markuplint/commit/abd81e5d20f4ffeb0ba878e77fd4122c1a803a9f))
+
+### Performance Improvements
+
+* **ml-core:** guard debug logging on the rule mapper and verify paths ([1a6249f](https://github.com/markuplint/markuplint/commit/1a6249f333e2dc75d65607b5059f9d8d647e7b3b))
+
+
+# [5.2.0](https://github.com/markuplint/markuplint/compare/v5.1.1...v5.2.0) (2026-10-13)
+
+### Bug Fixes
+
+- **ml-core:** resolve the namespace of a component and the children given to it ([00ecbba](https://github.com/markuplint/markuplint/commit/00ecbbae6095dd8eb7d10148633d6610bed7f1e2))
+- **ml-core:** return the DOM values from MLAttr.namespaceURI ([05467ad](https://github.com/markuplint/markuplint/commit/05467ad28d61ae0a272c8335db9a0b2f614e5592))
+- use caret ranges for third-party dependencies of published packages ([5fb5d2e](https://github.com/markuplint/markuplint/commit/5fb5d2ee81eaeea45fe7256a40dd41c95ff0d672))
+
 ## [5.1.1](https://github.com/markuplint/markuplint/compare/v5.1.0...v5.1.1) (2026-10-09)
 
 **Note:** Version bump only for package @markuplint/ml-core

package/CLAUDE.md

@@ -0,0 +1,11 @@
+# @markuplint/ml-core
+
+## Keeping the MLDOM classes in step with `lib.dom`
+
+`MLElement`, `MLNode`, `MLAttr` and the other MLDOM classes `implements` the DOM interfaces, so a TypeScript release that adds a property or makes one nullable breaks the build with a long list of "is missing the following properties" errors. Fix that by adding the missing stubs and widening types to `| null` where `lib.dom` did, one stub at a time, rebuilding between rounds.
+
+Do not change a parameter or return type from an MLDOM class to the plain DOM type (`MLElement` → `Element`, `MLNode` → `Node`) to make the errors go away. That drops the markuplint-specific type information for every caller, and the error cascade it seems to cure is only the missing stubs. Adding a method overload (for example on `matches()`) counts as a stub and is fine.
+
+## Consumer reports of a type error after a TypeScript release
+
+The `implements` clauses land in the published `.d.ts`, so a consumer whose `lib.dom` is newer than ours (a newer TypeScript, or `libReplacement` with third-party DOM types) gets the same "is missing the following properties" errors from `node_modules/@markuplint/ml-core` without changing anything on their side; `skipLibCheck: false` is enough. Adding the stubs here fixes our build, and the consumer only once they upgrade markuplint. The structural fix — drop `implements` from the public classes and move DOM conformance to a typecheck spec that is not published (`yarn test:types` now type-checks the specs) — is tracked in #4076; check its state before closing another such report with a stub-only release.

package/lib/debug.d.ts

@@ -1,4 +1,10 @@
 import debug from 'debug';
+/**
+ * Read `.enabled` at call time; never cache it at module load. `debug.enable()` (including via `verbosely()` /
+ * `enableDebug()`) can switch a namespace on after import. A verify or fix run reads it once on entry to decide
+ * whether to build log arguments. Enabling debug mid-run is not seen until the next run; disabling takes effect at
+ * once because the logger itself re-checks.
+ */
 export declare const log: debug.Debugger;
 /**
  * Enables debug logging for the `ml-core` namespace and the CLI namespace.

package/lib/debug.js

@@ -1,5 +1,11 @@
 import debug from 'debug';
 const CLI_NS = 'markuplint-cli';
+/**
+ * Read `.enabled` at call time; never cache it at module load. `debug.enable()` (including via `verbosely()` /
+ * `enableDebug()`) can switch a namespace on after import. A verify or fix run reads it once on entry to decide
+ * whether to build log arguments. Enabling debug mid-run is not seen until the next run; disabling takes effect at
+ * once because the logger itself re-checks.
+ */
 export const log = debug('ml-core');
 /**
  * Enables debug logging for the `ml-core` namespace and the CLI namespace.

package/lib/ml-core.js

@@ -191,7 +191,10 @@ export class MLCore {
     async verify(fixOrOptions) {
         const options = typeof fixOrOptions === 'boolean' ? { fix: fixOrOptions } : (fixOrOptions ?? {});
         const fix = options.fix ?? false;
-        log('verify: start');
+        const logEnabled = log.enabled;
+        if (logEnabled) {
+            log('verify: start');
+        }
         const violations = [];
         if (this.#document instanceof ParserError) {
             const parseError = this.#createParseError(this.#document.message, this.#document.line, this.#document.col, this.#document.raw);
@@ -199,7 +202,9 @@ export class MLCore {
                 return { violations: [], fixedCode: fix ? this.#sourceCode : undefined };
             }
             violations.push(parseError);
-            log('verify: error %o', this.#document.message);
+            if (logEnabled) {
+                log('verify: error %o', this.#document.message);
+            }
             return { violations, fixedCode: fix ? this.#sourceCode : undefined };
         }
         this.#pushNonFatalParseErrors(violations);
@@ -321,7 +326,9 @@ export class MLCore {
                 };
             }
         }
-        log('verify: end');
+        if (logEnabled) {
+            log('verify: end');
+        }
         return { violations, fixedCode, fixSummary };
     }
     #createDocument() {
@@ -338,6 +345,12 @@ export class MLCore {
                 endTag: this.#parser.endTag,
                 booleanish: this.#parser.booleanish,
                 tagNameCaseSensitive: this.#parser.tagNameCaseSensitive,
+                componentNameVariants: this.#parser.componentNameVariants,
+                // The parser's own rule, called on the parser: a method of a class that reads its own state
+                isComponentName: this.#parser.isComponentName?.bind(this.#parser),
+                isNativeTag: this.#parser.isNativeTag?.bind(this.#parser),
+                attrNameCaseSensitive: this.#parser.attrNameCaseSensitive,
+                attrNameRoute: this.#parser.attrNameRoute,
                 pretenders: this.#pretenders,
             });
             // Collect errors from rule mapping (e.g., invalid wildcard usage).
@@ -494,6 +507,7 @@ export class MLCore {
     async #multiPassFix(initialViolations) {
         // Same safety cap as ESLint's SourceCodeFixer (10 passes).
         const MAX_FIX_PASSES = 10;
+        const logEnabled = log.enabled;
         let currentCode = this.#sourceCode;
         let fixes = extractFixes(initialViolations);
         let totalApplied = 0;
@@ -511,7 +525,9 @@ export class MLCore {
         let lastParsableCode = currentCode;
         let pass = 0;
         for (; pass < MAX_FIX_PASSES; pass++) {
-            log('fix pass %d: %d fixes', pass, fixes.length);
+            if (logEnabled) {
+                log('fix pass %d: %d fixes', pass, fixes.length);
+            }
             const result = applyFixes(currentCode, fixes);
             totalApplied += result.applied.length;
             totalSkipped += result.skipped.length;
@@ -519,18 +535,24 @@ export class MLCore {
                 firstPassEdits = result.appliedEdits;
             }
             if (result.applied.length === 0) {
-                log('fix pass %d: no fixes applied, stopping', pass);
+                if (logEnabled) {
+                    log('fix pass %d: no fixes applied, stopping', pass);
+                }
                 break;
             }
             if (result.output === currentCode) {
-                log('fix pass %d: output unchanged, stopping', pass);
+                if (logEnabled) {
+                    log('fix pass %d: output unchanged, stopping', pass);
+                }
                 break;
             }
             // 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);
+                if (logEnabled) {
+                    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;
@@ -545,7 +567,9 @@ export class MLCore {
             this.#parse();
             this.#createDocument();
             if (this.#document instanceof ParserError) {
-                log('fix pass %d: produced unparsable code, reverting to the previous parsable code', pass);
+                if (logEnabled) {
+                    log('fix pass %d: produced unparsable code, reverting to the previous parsable code', pass);
+                }
                 currentCode = lastParsableCode;
                 totalApplied -= result.applied.length;
                 if (pass === 0) {
@@ -555,21 +579,27 @@ export class MLCore {
             }
             lastParsableCode = currentCode;
             if (result.skipped.length === 0) {
-                log('fix pass %d: all fixes applied, stopping', pass);
+                if (logEnabled) {
+                    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);
+            if (logEnabled) {
+                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);
+                if (logEnabled) {
+                    log('fix pass %d: no more fixable violations, stopping', pass);
+                }
                 break;
             }
         }
         const reachedMaxPasses = pass === MAX_FIX_PASSES;
-        if (reachedMaxPasses) {
+        if (reachedMaxPasses && logEnabled) {
             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
@@ -608,6 +638,7 @@ export class MLCore {
         };
     }
     async #runAllRules(fix) {
+        const logEnabled = log.enabled;
         const violations = [];
         if (this.#document instanceof ParserError) {
             return violations;
@@ -629,7 +660,9 @@ export class MLCore {
             if (ruleInfo.disabled && ruleInfo.nodeRules.length === 0 && ruleInfo.childNodeRules.length === 0) {
                 continue;
             }
-            log('%s Rule: verify', rule.name);
+            if (logEnabled) {
+                log('%s Rule: verify', rule.name);
+            }
             const results = await rule.verify(this.#document, this.#locale, fix).catch(error => {
                 if (error instanceof ParserError) {
                     return error;
@@ -639,14 +672,18 @@ export class MLCore {
             if (results instanceof ParserError) {
                 const parseError = this.#createParseError(results.message, results.line, results.col, results.raw);
                 if (parseError) {
-                    log('%s Rule: verify error %o', rule.name, results.message);
+                    if (logEnabled) {
+                        log('%s Rule: verify error %o', rule.name, results.message);
+                    }
                     violations.push(parseError);
                 }
             }
             else {
                 violations.push(...results);
             }
-            log('%s Rule: verify end', rule.name);
+            if (logEnabled) {
+                log('%s Rule: verify end', rule.name);
+            }
         }
         return violations;
     }
@@ -655,7 +692,9 @@ export class MLCore {
             this.#ast = this.#parser.parse(this.#sourceCode, this.#parserOptions);
         }
         catch (error) {
-            log('Caught the parse error: %O', error);
+            if (log.enabled) {
+                log('Caught the parse error: %O', error);
+            }
             this.#ast = null;
             if (error instanceof ParserError) {
                 this.#document = error;

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

@@ -23,8 +23,10 @@ el, version) {
         return result.name;
     }
     catch (error) {
-        accnameLog('Raw: %s', el.raw);
-        accnameLog('Error: %O', error);
+        if (accnameLog.enabled) {
+            accnameLog('Raw: %s', el.raw);
+            accnameLog('Error: %O', error);
+        }
         return '';
     }
 }

package/lib/ml-dom/helper/foreign-attr-names.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The name that the HTML parser gives an attribute of an element in a foreign namespace: the name
+ * lower-cased, with the case restored for the names of SVG (`viewbox` is `viewBox`) and MathML
+ * (`definitionurl` is `definitionURL`).
+ *
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#adjust-svg-attributes
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#adjust-mathml-attributes
+ *
+ * @param lowerCaseName - The name with its ASCII letters lower-cased
+ * @param namespaceURI - The namespace of the element that the attribute is on
+ * @returns The name in the DOM
+ */
+export declare function adjustForeignAttrName(lowerCaseName: string, namespaceURI: string | null): string;

package/lib/ml-dom/helper/foreign-attr-names.js

@@ -0,0 +1,89 @@
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+const MATHML_NAMESPACE = 'http://www.w3.org/1998/Math/MathML';
+/**
+ * The names of SVG attributes that are not all lower case, the second column of the table of
+ * "adjust SVG attributes". The HTML parser lower-cases a name it reads and then restores these.
+ *
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#adjust-svg-attributes
+ */
+const SVG_ATTR_NAMES = new Map([
+    'attributeName',
+    'attributeType',
+    'baseFrequency',
+    'baseProfile',
+    'calcMode',
+    'clipPathUnits',
+    'diffuseConstant',
+    'edgeMode',
+    'filterUnits',
+    'glyphRef',
+    'gradientTransform',
+    'gradientUnits',
+    'kernelMatrix',
+    'kernelUnitLength',
+    'keyPoints',
+    'keySplines',
+    'keyTimes',
+    'lengthAdjust',
+    'limitingConeAngle',
+    'markerHeight',
+    'markerUnits',
+    'markerWidth',
+    'maskContentUnits',
+    'maskUnits',
+    'numOctaves',
+    'pathLength',
+    'patternContentUnits',
+    'patternTransform',
+    'patternUnits',
+    'pointsAtX',
+    'pointsAtY',
+    'pointsAtZ',
+    'preserveAlpha',
+    'preserveAspectRatio',
+    'primitiveUnits',
+    'refX',
+    'refY',
+    'repeatCount',
+    'repeatDur',
+    'requiredExtensions',
+    'requiredFeatures',
+    'specularConstant',
+    'specularExponent',
+    'spreadMethod',
+    'startOffset',
+    'stdDeviation',
+    'stitchTiles',
+    'surfaceScale',
+    'systemLanguage',
+    'tableValues',
+    'targetX',
+    'targetY',
+    'textLength',
+    'viewBox',
+    'viewTarget',
+    'xChannelSelector',
+    'yChannelSelector',
+    'zoomAndPan',
+].map(name => [name.toLowerCase(), name]));
+/**
+ * The name that the HTML parser gives an attribute of an element in a foreign namespace: the name
+ * lower-cased, with the case restored for the names of SVG (`viewbox` is `viewBox`) and MathML
+ * (`definitionurl` is `definitionURL`).
+ *
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#adjust-svg-attributes
+ * @see https://html.spec.whatwg.org/multipage/parsing.html#adjust-mathml-attributes
+ *
+ * @param lowerCaseName - The name with its ASCII letters lower-cased
+ * @param namespaceURI - The namespace of the element that the attribute is on
+ * @returns The name in the DOM
+ */
+export function adjustForeignAttrName(lowerCaseName, namespaceURI) {
+    if (namespaceURI === SVG_NAMESPACE) {
+        return SVG_ATTR_NAMES.get(lowerCaseName) ?? lowerCaseName;
+    }
+    if (namespaceURI === MATHML_NAMESPACE && lowerCaseName === 'definitionurl') {
+        return 'definitionURL';
+    }
+    return lowerCaseName;
+}

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

@@ -98,7 +98,86 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      */
     get name(): string;
     /**
-     * Returns the namespace URI of this attribute, resolved from the attribute name.
+     * The name that the DOM gives this attribute, which two spellings of a name share when they are
+     * one attribute (`ID` and `id` on a `<div>`, `VIEWBOX` and `viewbox` on an `<svg>` that the
+     * HTML parser reads). `name` keeps the spelling of the source for a message, and for
+     * `case-sensitive-attr-name`.
+     *
+     * It depends on how the name gets into the DOM (`MLDocument#attrNameRoute`) and on the element:
+     * the HTML parser lower-cases a name, and restores the case of the names of SVG and MathML;
+     * `setAttribute` lower-cases a name only on an element of the HTML namespace, so `ROLE` on an
+     * `<svg>` that code sets is `ROLE`, which is not `role`. The attribute of a component is a prop,
+     * which keeps its spelling, except in Vue where `my-label` and `myLabel` are one prop.
+     *
+     * @see https://dom.spec.whatwg.org/#dom-element-setattribute
+     * @see https://html.spec.whatwg.org/multipage/parsing.html#attribute-name-state
+     */
+    get nameKey(): string;
+    /**
+     * The key of `name`, a name of a spec, of an option or of a lookup, as this attribute is keyed:
+     * `name` is this attribute when its key is {@link MLAttr.nameKey}. Only the ASCII letters fold,
+     * as the HTML syntax says (`toLowerCase` also turns U+212A KELVIN SIGN into `k`).
+     *
+     * It is computed when asked, not stored by the constructor: it reads the owner element (its
+     * type and namespace) and the document, which are complete only after the attribute is built.
+     *
+     * @param name - A name as written
+     * @returns The key that two spellings of one attribute share
+     */
+    keyOf(name: string): string;
+    /**
+     * Whether `name` is the name of this attribute: the spelling it is written in, or another that
+     * the DOM makes the same attribute ({@link MLAttr.keyOf}). A spec, an option and the lookups of
+     * the element ask this, so the case of a name is decided here and not in each of them.
+     *
+     * A name with a capital letter that code sets on an element of the HTML namespace is a prop of
+     * the framework (`defaultValue` of React), not an attribute of the DOM: only its exact spelling
+     * is it, and `defaultvalue` is not (see {@link MLAttr.isPrefixedBy} for a prefix).
+     *
+     * @param name - A name of a spec, an option or a lookup
+     * @returns `true` if `name` is this attribute
+     */
+    isNamedBy(name: string): boolean;
+    /**
+     * Whether the name of this attribute starts with `prefix`, a prefix of an option
+     * (`ignoreAttrNamePrefix`): as it is written, or as the DOM gives the name ({@link MLAttr.keyOf}).
+     * A prefix with a capital letter that code sets on an element of the HTML namespace is the prefix
+     * of a name of the framework, and only its exact spelling is it, as for {@link MLAttr.isNamedBy}.
+     *
+     * @param prefix - A prefix of an option
+     * @returns `true` if the name of this attribute starts with `prefix`
+     */
+    isPrefixedBy(prefix: string): boolean;
+    /**
+     * Whether the name of this attribute reaches the DOM through the DOM API (`setAttribute`) and
+     * not through the HTML parser of the browser: what the parser says of its language
+     * (`MLDocument#attrNameRoute`), and for a parser that says it of a dynamic attribute only
+     * (Svelte), whether this one is dynamic.
+     */
+    get isSetThroughDOMAPI(): boolean;
+    /**
+     * Whether a selector matches the name of this attribute without regard to ASCII case: the DOM
+     * does so for an element of the HTML namespace and not for one of SVG or MathML, nor for a prop.
+     *
+     * @implements `SelectorAttr#nameCaseInsensitive` of `@markuplint/selector`
+     */
+    get nameCaseInsensitive(): boolean;
+    /**
+     * The name that a selector is matched with.
+     *
+     * @implements `SelectorAttr#domName` of `@markuplint/selector`
+     */
+    get domName(): string;
+    /**
+     * Whether a name of a selector is this prop once it is camelized: the props of a Vue component.
+     *
+     * @implements `SelectorAttr#nameIsCamelized` of `@markuplint/selector`
+     */
+    get nameIsCamelized(): boolean;
+    /**
+     * Returns the namespace URI of this attribute: that of its prefix when the name has a known
+     * one (e.g. `xlink:href`), otherwise `null`. An attribute without a prefix has no namespace
+     * whichever element it is on, and so does a spread attribute.
      *
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-attr-namespaceuri