@markuplint/rules 5.2.0 → 5.4.0

package/lib/no-refer-to-non-existent-id/index.js

@@ -1,6 +1,7 @@
 import { createRule, getAttrSpecs, ariaSpecs } from '@markuplint/ml-core';
 import { ARIA_RECOMMENDED_VERSION } from '@markuplint/ml-spec';
 import { decodeEntities } from '@markuplint/shared';
+import { findAttrSpec } from '../helpers.js';
 import meta from './meta.js';
 export default createRule({
     meta: meta,
@@ -37,12 +38,11 @@ export default createRule({
             if (attr.isDynamicValue) {
                 return;
             }
-            const name = attr.name;
-            if (name.toLowerCase() === 'id') {
+            if (attr.nameKey === 'id') {
                 return;
             }
             const value = attr.value;
-            const spec = attrSpec.find(s => s.name === name);
+            const spec = findAttrSpec(attrSpec, attr);
             if (spec) {
                 // DOMID and DOMID List do not become in the array type.
                 if (Array.isArray(spec.type)) {
@@ -76,7 +76,7 @@ export default createRule({
                 }
             }
             const { props } = ariaSpecs(document.specs, attr.rule.options.ariaVersion ?? document.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION);
-            const aria = props.find(prop => prop.name === name);
+            const aria = props.find(prop => prop.name === attr.nameKey);
             if (aria) {
                 if (aria.value === 'ID reference' && !idList.has(value)) {
                     report({

package/lib/no-restricted-attr/index.d.ts

@@ -10,6 +10,10 @@ type Option = {
      * already restricts. This is the rule's only concern — narrow, purely
      * user-defined denylisting, independent of spec conformance.
      *
+     * A name is compared as the DOM compares attribute names, so it is ASCII case-insensitive in the
+     * HTML syntax and for an HTML element that code sets through the DOM API (JSX, MDX, Vue), exact for an
+     * SVG/MathML element there, and a component's props are not folded.
+     *
      * @since 3.7.0
      */
     disallowAttrs?: (string | Attr)[] | Record<string, AttributeType | Pattern>;

package/lib/no-restricted-attr/index.js

@@ -1,32 +1,15 @@
 import { createRule } from '@markuplint/ml-core';
 import { check, isEnum, isPattern } from '@markuplint/types';
 import { attrCheck } from '../attr-check.js';
+import { createNameOptionLookup } from '../helpers.js';
 import meta from './meta.js';
-function disallowedTypes(disallowAttrs) {
-    const map = new Map();
-    if (!disallowAttrs) {
-        return map;
-    }
-    if (Array.isArray(disallowAttrs)) {
-        for (const disallowAttr of disallowAttrs) {
-            if (typeof disallowAttr === 'string') {
-                map.set(disallowAttr, 'Any');
-                continue;
-            }
-            map.set(disallowAttr.name, disallowAttr.value);
-        }
-    }
-    else {
-        for (const [name, type] of Object.entries(disallowAttrs)) {
-            map.set(name, type);
-        }
-    }
-    return map;
-}
 export default createRule({
     meta: meta,
     defaultOptions: {},
     async verify({ document, report, t }) {
+        // Whether an entry of `disallowAttrs` is the attribute is up to the attribute: the DOM decides
+        // whether two spellings are one name (`MLAttr#isNamedBy`).
+        const lookupDisallowed = createNameOptionLookup('Any');
         await document.walkOn('Attr', attr => {
             if (attr.isDirective) {
                 return;
@@ -35,7 +18,7 @@ export default createRule({
             const value = attr.value;
             const valueNode = attr.valueNode;
             const attrName = attr.nameNode;
-            const disallowValue = disallowedTypes(attr.rule.options.disallowAttrs).get(name);
+            const disallowValue = lookupDisallowed(attr.rule.options.disallowAttrs, attr);
             if (disallowValue === undefined) {
                 return;
             }

package/lib/no-stray-head-or-body-tag/index.d.ts

@@ -4,13 +4,15 @@
  * > A start tag whose tag name is "body": Parse error. If the stack of open
  * > elements has only one node on it, or if the second element on the stack
  * > of open elements is not a body element, or if there is a template
- * > element on the stack of open elements, then ignore the token […].
- * > Otherwise, set the frameset-ok flag to "not ok" […]
+ * > element on the stack of open elements, then ignore the token. […]
+ * > Otherwise: Set the frameset-ok flag to "not ok" […]
  *
  * "in body" insertion mode, "Any other end tag":
  *
- * > Initialize node to be the current node […]. If node's tag name […] is
- * > not the same as the tag name of the token, then this is a parse error.
+ * > Initialize node to be the current node (the bottommost node of the
+ * > stack). Loop: If node is an HTML element with the same tag name as the
+ * > token: […] Otherwise, if node is in the special category, then this is a
+ * > parse error; ignore the token, and return.
  *
  * Neither of these fires by the presence of disallowed `<head>` content
  * itself (the "in head" insertion mode's own "Anything else" clause that

package/lib/no-stray-head-or-body-tag/index.js

@@ -5,9 +5,12 @@ import meta from './meta.js';
  * "generic raw text element parsing algorithm" / "generic RCDATA element
  * parsing algorithm"): the parser never re-tokenizes tag-shaped substrings
  * inside it, so a literal `<body` or `</head` there is ordinary text, not a
- * candidate for either check below.
+ * candidate for either check below. `iframe`, `noembed` and `noframes` are
+ * RAWTEXT too but `@markuplint/parser-utils` still tokenizes their content
+ * as markup (`permitted-contents` relies on that), so they are skipped here
+ * rather than in the parser (#4180).
  */
-const RAW_TEXT_CONTAINERS = new Set(['script', 'style', 'title', 'textarea', 'xmp']);
+const RAW_TEXT_CONTAINERS = new Set(['script', 'style', 'title', 'textarea', 'xmp', 'iframe', 'noembed', 'noframes']);
 const STRAY_HEAD_END_TAG = /<\/head(?=[\s/>])/i;
 const DUPLICATE_BODY_START_TAG = /<body(?=[\s/>])/i;
 /**
@@ -16,13 +19,15 @@ const DUPLICATE_BODY_START_TAG = /<body(?=[\s/>])/i;
  * > A start tag whose tag name is "body": Parse error. If the stack of open
  * > elements has only one node on it, or if the second element on the stack
  * > of open elements is not a body element, or if there is a template
- * > element on the stack of open elements, then ignore the token […].
- * > Otherwise, set the frameset-ok flag to "not ok" […]
+ * > element on the stack of open elements, then ignore the token. […]
+ * > Otherwise: Set the frameset-ok flag to "not ok" […]
  *
  * "in body" insertion mode, "Any other end tag":
  *
- * > Initialize node to be the current node […]. If node's tag name […] is
- * > not the same as the tag name of the token, then this is a parse error.
+ * > Initialize node to be the current node (the bottommost node of the
+ * > stack). Loop: If node is an HTML element with the same tag name as the
+ * > token: […] Otherwise, if node is in the special category, then this is a
+ * > parse error; ignore the token, and return.
  *
  * Neither of these fires by the presence of disallowed `<head>` content
  * itself (the "in head" insertion mode's own "Anything else" clause that

package/lib/no-unknown-attr/index.d.ts

@@ -9,10 +9,16 @@ type Option = {
      * The value type is used by `no-invalid-attr-value` to validate the
      * attribute's value; here it only determines whether the name is known.
      *
+     * A name is compared as the DOM compares attribute names.
+     *
+     * @see https://markuplint.dev/docs/rules/no-unknown-attr#attribute-name-case
      * @since 3.7.0
      */
     allowAttrs?: (string | Attr)[] | Record<string, AttributeType | Pattern>;
-    /** Attribute name prefix(es) to ignore during validation. */
+    /**
+     * Attribute name prefix(es) to ignore during validation, compared as the DOM compares attribute
+     * names, like `allowAttrs`.
+     */
     ignoreAttrNamePrefix?: string | string[];
     /** Whether to allow additional properties for pretender elements (defaults to `true`). */
     allowToAddPropertiesForPretender?: boolean;

package/lib/no-unknown-attr/index.js

@@ -1,19 +1,15 @@
 import { createRule, getAttrSpecs, getSpec } from '@markuplint/ml-core';
 import { resolveAttrEligibility, suggestionSuffix } from '../attr-eligibility.js';
+import { createNameOptionLookup, createPrefixMatcher } from '../helpers.js';
 import meta from './meta.js';
-function allowedNames(allowAttrs) {
-    if (!allowAttrs) {
-        return new Set();
-    }
-    if (Array.isArray(allowAttrs)) {
-        return new Set(allowAttrs.map(a => (typeof a === 'string' ? a : a.name)));
-    }
-    return new Set(Object.keys(allowAttrs));
-}
 export default createRule({
     meta: meta,
     defaultOptions: {},
     async verify({ document, report, t }) {
+        // Whether an entry of the options is the attribute is up to the attribute: the DOM decides
+        // whether two spellings are one name (`MLAttr#isNamedBy`, `MLAttr#isPrefixedBy`).
+        const lookupAllowed = createNameOptionLookup('Any');
+        const hasIgnoredPrefix = createPrefixMatcher();
         await document.walkOn('Attr', attr => {
             if (attr.isDirective) {
                 return;
@@ -31,19 +27,15 @@ export default createRule({
                     raw: attrName?.raw,
                     message: t('{0} is {1:c}', t('the "{0*}" {1}', name, 'attribute'), 'disallowed') +
                         t('. ') +
-                        t('Did you mean "{0}"?', attr.candidate),
+                        t('Did you mean "{0*}"?', attr.candidate),
                 });
                 return;
             }
-            if (attr.rule.options.ignoreAttrNamePrefix != null) {
-                const prefixes = Array.isArray(attr.rule.options.ignoreAttrNamePrefix)
-                    ? attr.rule.options.ignoreAttrNamePrefix
-                    : [attr.rule.options.ignoreAttrNamePrefix];
-                if (prefixes.some(prefix => name.indexOf(prefix) === 0)) {
-                    return;
-                }
+            if (hasIgnoredPrefix(attr.rule.options.ignoreAttrNamePrefix, attr)) {
+                return;
             }
-            if (allowedNames(attr.rule.options.allowAttrs).has(name)) {
+            // A name listed in `allowAttrs` is allowed whatever its value
+            if (lookupAllowed(attr.rule.options.allowAttrs, attr) !== undefined) {
                 return;
             }
             if (attr.ownerElement.elementType !== 'html') {
@@ -53,7 +45,7 @@ export default createRule({
             if (!attrSpecs) {
                 return;
             }
-            const eligibility = resolveAttrEligibility(name, attr.ownerElement, attrSpecs);
+            const eligibility = resolveAttrEligibility(name, attr.ownerElement, attrSpecs, attr);
             let message;
             switch (eligibility.status) {
                 case 'unknown': {
@@ -62,12 +54,6 @@ export default createRule({
                             suggestionSuffix(t, eligibility.candidate);
                     break;
                 }
-                case 'case-mismatch': {
-                    message =
-                        t('{0} is {1:c}', t('the "{0*}" {1}', name, 'attribute'), 'disallowed') +
-                            suggestionSuffix(t, eligibility.expectedName);
-                    break;
-                }
                 default: {
                     return;
                 }

package/lib/no-unpaired-srcset-sizes/index.d.ts

@@ -5,8 +5,9 @@
  * one constraint.
  *
  * `<source>`'s direction (Check 5) is conditional: `sizes` "may" be omitted
- * when the following sibling `<img>` has `loading="lazy"` (auto-sizes
- * support). `<img>`'s direction (Check 1) has no such escape.
+ * when the following sibling `<img>` allows auto-sizes (`loading="lazy"` and
+ * `sizes="auto"`; see `allowsAutoSizes`). `<img>`'s direction (Check 1) has no
+ * such escape.
  */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, undefined>>;
 export default _default;

package/lib/no-unpaired-srcset-sizes/index.js

@@ -1,6 +1,6 @@
 import { createRule } from '@markuplint/ml-core';
 import { parseSrcset } from '../srcset-sizes-constraint/parse-srcset.js';
-import { findFollowingImg } from '../srcset-sizes-constraint/sibling-helpers.js';
+import { allowsAutoSizes, findFollowingImg, isLazyLoading } from '../srcset-sizes-constraint/sibling-helpers.js';
 import meta from './meta.js';
 /**
  * HTML LS § img/source `srcset` attributes: `sizes` and a width-descriptor
@@ -9,8 +9,9 @@ import meta from './meta.js';
  * one constraint.
  *
  * `<source>`'s direction (Check 5) is conditional: `sizes` "may" be omitted
- * when the following sibling `<img>` has `loading="lazy"` (auto-sizes
- * support). `<img>`'s direction (Check 1) has no such escape.
+ * when the following sibling `<img>` allows auto-sizes (`loading="lazy"` and
+ * `sizes="auto"`; see `allowsAutoSizes`). `<img>`'s direction (Check 1) has no
+ * such escape.
  */
 export default createRule({
     meta,
@@ -50,25 +51,30 @@ export default createRule({
             }
             // img / source-in-picture with w descriptors → sizes required.
             //
-            // HTML LS § img srcset: unconditional — "the sizes attribute must
-            // also be present" when any candidate uses a width descriptor.
+            // HTML LS § img srcset: unconditional — the sizes attribute must
+            // also be present when any candidate uses a width descriptor.
             //
-            // HTML LS § source: conditional — sizes "may" be present with w
-            // descriptors, but the following sibling img must support
-            // auto-sizes for it to be omittable. img supports auto-sizes when
-            // loading=lazy (the dimensionsAttribute condition is also part of
-            // the spec but the lazy attribute is the user-facing trigger).
+            // HTML LS § source: conditional — sizes may be omitted only when
+            // the following sibling img allows auto-sizes (loading=lazy and
+            // sizes=auto; the same condition is the second source of truth for
+            // `sizes-auto-requires-lazy-loading`).
+            //
+            // @see https://html.spec.whatwg.org/multipage/embedded-content.html#allows-auto-sizes
             if (parsed && parsed.hasWidth && !sizesAttr) {
                 // For `<source>`, `findFollowingImg` may return null (malformed
-                // <picture> with no img). Optional chaining short-circuits to
-                // undefined, and `undefined === 'lazy'` is false → sizes is
-                // required. That's the correct fail-closed behaviour: an absent
-                // img cannot supply auto-sizes for the source.
-                const siblingImgLazy = localName === 'source' && findFollowingImg(el)?.getAttribute('loading') === 'lazy';
-                if (!siblingImgLazy) {
+                // <picture> with no img): an absent img cannot supply
+                // auto-sizes, so sizes is required (fail-closed). A dynamic
+                // `loading` / `sizes` on the img is not known → not reported.
+                const img = localName === 'source' ? findFollowingImg(el) : null;
+                if (!img || allowsAutoSizes(img) === false) {
+                    // A lazy img that is not auto-sized is the case a reader
+                    // least expects to be rejected: name what would allow it.
+                    const needsImgSizes = img != null && isLazyLoading(img) === true;
                     report({
                         scope: el,
-                        message: 'The "sizes" attribute is required when the "srcset" attribute uses width descriptors',
+                        message: needsImgSizes
+                            ? 'The "sizes" attribute is required when the "srcset" attribute uses width descriptors, unless the following sibling "img" element has loading="lazy" and sizes="auto"'
+                            : 'The "sizes" attribute is required when the "srcset" attribute uses width descriptors',
                     });
                 }
             }

package/lib/no-unsupported-browser-features/compat-data.d.ts

@@ -1,3 +1,5 @@
+import type { PlainData } from '@markuplint/ml-config';
+import type { Attr, RuleConfigValue } from '@markuplint/ml-core';
 import type { BrowserName, SupportStatement } from '@mdn/browser-compat-data';
 /**
  * Target browser with name and minimum version.
@@ -60,12 +62,23 @@ export declare function checkSupport(support: SupportStatement | undefined, targ
  * @returns Array of unsupported results (empty if all supported)
  */
 export declare function checkElementSupport(elementName: string, targets: readonly TargetBrowser[]): Promise<readonly UnsupportedResult[]>;
+/**
+ * What the lookup of an attribute asks of the attribute: its name as the DOM gives it, and the name
+ * the DOM would give a key of BCD (`MLAttr#nameKey`, `MLAttr#keyOf`).
+ *
+ * It does not ask `MLAttr#isNamedBy`: that reads a name with a capital letter as the prop of a
+ * framework (`defaultValue`) and matches only its exact spelling, but a key of BCD is the spelling of
+ * an attribute of the browser, which the DOM folds (`privateToken` is `privatetoken`).
+ */
+export type CompatAttr = Pick<Attr<RuleConfigValue, PlainData>, 'nameKey' | 'keyOf'>;
 /**
  * Check browser support for an HTML attribute on a specific element.
  *
  * @param elementName - The HTML element name (e.g., "input")
- * @param attrName - The attribute name (e.g., "list")
+ * @param attrName - The attribute name (e.g., "list"), as written
  * @param targets - Array of target browsers to check
+ * @param attr - The attribute, which decides whether a key of BCD that is spelled in another case is
+ *   the attribute (the DOM folds a name that the HTML parser reads, and not a prop of a framework)
  * @returns Array of unsupported results (empty if all supported)
  */
-export declare function checkAttributeSupport(elementName: string, attrName: string, targets: readonly TargetBrowser[]): Promise<readonly UnsupportedResult[]>;
+export declare function checkAttributeSupport(elementName: string, attrName: string, targets: readonly TargetBrowser[], attr?: CompatAttr): Promise<readonly UnsupportedResult[]>;

package/lib/no-unsupported-browser-features/compat-data.js

@@ -1,3 +1,5 @@
+import { asciiLowerCase } from '@markuplint/shared';
+import { memoizeByObject } from '../helpers.js';
 /**
  * Mapping from browserslist browser names to BCD browser names.
  */
@@ -187,20 +189,63 @@ export async function checkElementSupport(elementName, targets) {
     }
     return results;
 }
+/**
+ * The keys of an element identifier by the key in ASCII lower case. BCD spells a few keys in camel
+ * case (`iframe.privateToken`), and the DOM can make a written name one of them (`PRIVATETOKEN` that
+ * the HTML parser folds), so the keys that a written name can be are found by this index and then
+ * asked of the attribute. It is built once per identifier, which BCD hands out as one object.
+ */
+const foldedKeysOf = memoizeByObject((identifier) => {
+    const folded = new Map();
+    for (const key of Object.keys(identifier)) {
+        if (key === '__compat') {
+            continue;
+        }
+        const lower = asciiLowerCase(key);
+        const keys = folded.get(lower);
+        if (keys) {
+            keys.push(key);
+        }
+        else {
+            folded.set(lower, [key]);
+        }
+    }
+    return folded;
+});
+/**
+ * Finds the identifier of an attribute in the identifier of its element. The key as written comes
+ * first. With the attribute, another key is the attribute when the attribute says its name is that
+ * key; without it, only the name in lower case is tried, as there is nothing to ask.
+ */
+function findAttrIdentifier(identifier, attrName, attr) {
+    const exact = identifier[attrName];
+    if (exact?.__compat) {
+        return exact;
+    }
+    if (!attr) {
+        return identifier[asciiLowerCase(attrName)];
+    }
+    const key = foldedKeysOf(identifier)
+        .get(asciiLowerCase(attr.nameKey))
+        ?.find(key => attr.keyOf(key) === attr.nameKey);
+    return key === undefined ? undefined : identifier[key];
+}
 /**
  * Check browser support for an HTML attribute on a specific element.
  *
  * @param elementName - The HTML element name (e.g., "input")
- * @param attrName - The attribute name (e.g., "list")
+ * @param attrName - The attribute name (e.g., "list"), as written
  * @param targets - Array of target browsers to check
+ * @param attr - The attribute, which decides whether a key of BCD that is spelled in another case is
+ *   the attribute (the DOM folds a name that the HTML parser reads, and not a prop of a framework)
  * @returns Array of unsupported results (empty if all supported)
  */
-export async function checkAttributeSupport(elementName, attrName, targets) {
+export async function checkAttributeSupport(elementName, attrName, targets, attr) {
     const identifier = await getElementIdentifier(elementName);
     if (!identifier) {
         return [];
     }
-    const attrIdentifier = identifier[attrName];
+    const attrIdentifier = findAttrIdentifier(identifier, attrName, attr);
     if (!attrIdentifier?.__compat) {
         return [];
     }

package/lib/no-unsupported-browser-features/index.d.ts

@@ -8,7 +8,11 @@ type Options = {
     readonly browserslistConfig?: string;
     /** Browserslist environment name (e.g., "production"). */
     readonly browserslistEnv?: string;
-    /** Features to ignore. Element name ("dialog") or attribute pattern ("input[list]"). */
+    /**
+     * Features to ignore: an element name ("dialog") or an attribute of an element ("input[list]"). The
+     * element name is compared as the document compares tag names, the attribute name as the DOM
+     * compares it with the attribute that is checked.
+     */
     readonly ignoreFeatures?: readonly string[];
 };
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;

package/lib/no-unsupported-browser-features/index.js

@@ -1,4 +1,5 @@
 import { createRule } from '@markuplint/ml-core';
+import { createIgnoreFeaturesLookup } from '../helpers.js';
 import { checkAttributeSupport, checkElementSupport } from './compat-data.js';
 import meta from './meta.js';
 import { clearBrowserslistCache, resolveTargetBrowsers } from './resolve-browsers.js';
@@ -17,7 +18,7 @@ export default createRule({
         if (targetBrowsers == null || targetBrowsers.length === 0) {
             return;
         }
-        const ignoreFeatures = new Set(options.ignoreFeatures);
+        const ignored = createIgnoreFeaturesLookup(document.tagNameCaseSensitive, options.ignoreFeatures);
         await document.walkOn('Element', async (el) => {
             // Web components and authored elements (JSX/Vue/Svelte) reach this rule
             // via `pretenders`: they masquerade as a known HTML element on `el.localName`,
@@ -27,9 +28,8 @@ export default createRule({
                 return;
             }
             const elName = el.localName;
-            const elOptions = el.rule.options;
-            const elIgnoreFeatures = new Set(elOptions.ignoreFeatures ?? ignoreFeatures);
-            if (!elIgnoreFeatures.has(elName)) {
+            const elIgnoreFeatures = el.rule.options.ignoreFeatures;
+            if (!ignored.isElementIgnored(elIgnoreFeatures, elName)) {
                 const unsupported = await checkElementSupport(elName, targetBrowsers);
                 if (unsupported.length > 0) {
                     report({
@@ -43,11 +43,10 @@ export default createRule({
                     continue;
                 }
                 const attrName = attr.name;
-                const ignoreKey = `${elName}[${attrName}]`;
-                if (elIgnoreFeatures.has(ignoreKey)) {
+                if (ignored.isAttrIgnored(elIgnoreFeatures, elName, attr)) {
                     continue;
                 }
-                const unsupported = await checkAttributeSupport(elName, attrName, targetBrowsers);
+                const unsupported = await checkAttributeSupport(elName, attrName, targetBrowsers, attr);
                 if (unsupported.length > 0) {
                     report({
                         scope: attr,

package/lib/permitted-contents/choice.js

@@ -1,4 +1,4 @@
-import { bgBlue, bgGreen, cmLog } from './debug.js';
+import { bgBlue, bgGreen, depthLog } from './debug.js';
 import { order } from './order.js';
 import { Collection, modelLog } from './utils.js';
 /**
@@ -29,17 +29,22 @@ const indexes = new WeakMap();
 export function choice(pattern, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNodes, rules, specs, options, depth, mode) {
-    const choiceLog = cmLog.extend(`choice#${depth}`);
+    const choiceLog = depthLog('choice', depth);
+    const choiceEnabled = choiceLog.enabled;
     const collection = new Collection(childNodes);
     const unmatchedResults = [];
     let i = 0;
     for (const some of pattern.choice) {
-        choiceLog('Patterns[%s]: %s', i, modelLog(some, ''));
+        if (choiceEnabled) {
+            choiceLog('Patterns[%s]: %s', i, modelLog(some, ''));
+        }
         const result = order(some, collection.unmatched, rules, specs, options, depth + 1, mode);
         if (result.type === 'MATCHED' ||
             result.type === 'MATCHED_ZERO' ||
             (result.type === 'UNEXPECTED_EXTRA_NODE' && result.matched.length > 0)) {
-            choiceLog('Results[%s]: %s', i, choiceLogString(pattern.choice, i));
+            if (choiceEnabled) {
+                choiceLog('Results[%s]: %s', i, choiceLogString(pattern.choice, i));
+            }
             return {
                 type: result.type,
                 matched: result.matched,
@@ -51,7 +56,11 @@ childNodes, rules, specs, options, depth, mode) {
         }
         unmatchedResults.push(result);
         collection.addMatched(result.matched);
-        indexes.set(result, i);
+        // Log-only bookkeeping. The `indexes.get()` below is guarded by the same `choiceEnabled`
+        // snapshot, so the two stay in step.
+        if (choiceEnabled) {
+            indexes.set(result, i);
+        }
         i++;
     }
     const barelyMatchedResult = unmatchedResults.toSorted((a, b) => {
@@ -75,9 +84,11 @@ childNodes, rules, specs, options, depth, mode) {
     if (!barelyMatchedResult) {
         throw new Error('Unreachable code');
     }
-    const index = indexes.get(barelyMatchedResult);
-    if (index != null) {
-        choiceLog('Results[%s]: %s', index, choiceLogString(pattern.choice, index, true));
+    if (choiceEnabled) {
+        const index = indexes.get(barelyMatchedResult);
+        if (index != null) {
+            choiceLog('Results[%s]: %s', index, choiceLogString(pattern.choice, index, true));
+        }
     }
     return {
         type: barelyMatchedResult.type,

package/lib/permitted-contents/content-model.d.ts

@@ -1,5 +1,5 @@
 import type { ContentModelResult, Element, Mode, Options, Specs, TagRule } from './types.js';
-import type { ContentModel } from '@markuplint/ml-spec';
+import type { ContentModel, MLMLSpec } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
  * Top-level entry point for content model validation of a single element.
@@ -30,3 +30,26 @@ export declare function contentModel(el: Element, rules: readonly TagRule[], opt
  * resolution logic when recursing into child content models.
  */
 export declare function resolveContentModel(el: Element, rules: readonly TagRule[], specs: Specs, mode: Mode): ReadonlyDeep<ContentModel['contents']> | null;
+/**
+ * Whether the user's tag rule is written for the element: the name of the rule is the name
+ * the element is written with, or another spelling of it that the document resolves to the
+ * same component (see `MLElement#matchesTagNameVariant`).
+ *
+ * @param el - The element
+ * @param rule - The user's tag rule
+ * @returns Whether the rule is written for the element
+ */
+export declare function hasTagRule(el: Element, rule: TagRule): boolean;
+/**
+ * Returns a Specs object that merges the base ML spec with user-defined
+ * tag rules. Results are cached by the specs of the document and the serialized rules to avoid redundant
+ * merging: the specs differ by document (the `specs` of the config is by file), so what is merged
+ * for one must not be given to another.
+ *
+ * Exported for the spec of the cache.
+ *
+ * @param specs - The base ML spec from the document.
+ * @param rules - User-defined tag rules to merge.
+ * @returns The merged Specs, either from cache or freshly computed.
+ */
+export declare function cachedSpecs(specs: MLMLSpec, rules: readonly TagRule[]): Specs;