@markuplint/rules 5.4.0 → 5.6.0

package/lib/permitted-contents/index.js

@@ -2,7 +2,7 @@ import { createRule } from '@markuplint/ml-core';
 import { contentModel, hasTagRule } from './content-model.js';
 import meta from './meta.js';
 import { transparentMode } from './represent-transparent-nodes.js';
-import { getContentOwner, getReportScope, isContentMutable } from './slot-content.js';
+import { getContentOwner, getReportScope, hasMutableChildNodes, isContentMutable } from './slot-content.js';
 export default createRule({
     meta: meta,
     defaultValue: [],
@@ -39,7 +39,7 @@ export default createRule({
                         case 'MISSING_NODE_ONE_OR_MORE': {
                             if (scope.rule.options.ignoreHasMutableChildren &&
                                 (!scope.is(scope.ELEMENT_NODE) ||
-                                    scope.hasMutableChildren() ||
+                                    hasMutableChildNodes(scope, mode) ||
                                     isContentMutable(el, mode))) {
                                 break;
                             }
@@ -59,7 +59,7 @@ export default createRule({
                         case 'MISSING_NODE_REQUIRED': {
                             if (scope.rule.options.ignoreHasMutableChildren &&
                                 (!scope.is(scope.ELEMENT_NODE) ||
-                                    scope.hasMutableChildren() ||
+                                    hasMutableChildNodes(scope, mode) ||
                                     isContentMutable(el, mode))) {
                                 break;
                             }
@@ -121,7 +121,8 @@ export default createRule({
 /**
  * Generates a localized, human-readable name for a child node based on its type.
  * Used in error messages to describe the offending node (e.g., 'the "div" element',
- * 'the text node', 'the comment', 'the doctype', 'the code block').
+ * 'the text node', 'the doctype', 'the code block'). A comment is not named: it is
+ * ignored when a content model is evaluated.
  *
  * In `'origin'` mode, uses {@link MLElement.rawName} so that the diagnostic refers
  * to the original AST identity (e.g. the component name `"Breadcrumbs"`) rather
@@ -138,14 +139,11 @@ function name(
 scope, t, mode) {
     if (scope.is(scope.ELEMENT_NODE)) {
         const displayName = mode === 'origin' ? scope.rawName : scope.localName;
-        return t('the "{0}" {1}', displayName, 'element');
+        return t('the "{0*}" {1}', displayName, 'element');
     }
     if (scope.is(scope.TEXT_NODE)) {
         return t('the {0}', 'text node');
     }
-    if (scope.is(scope.CDATA_SECTION_NODE)) {
-        return t('the {0}', 'comment');
-    }
     if (scope.is(scope.DOCUMENT_TYPE_NODE)) {
         return t('the {0}', 'doctype');
     }

package/lib/permitted-contents/matches-selector.js

@@ -1,4 +1,5 @@
 import { contentModelCategoryToTagNames } from '@markuplint/ml-spec';
+import { contentModelFirstChildBase, isContentModelFirstChild, isInterElementWhitespace } from '@markuplint/selector';
 import { depthLog } from './debug.js';
 import { cleanObject, matches } from './utils.js';
 /**
@@ -20,7 +21,7 @@ export function matchesSelector(query,
 childNode, specs, depth, mode) {
     const nodeLog = depthLog('node', depth);
     const nodeEnabled = nodeLog.enabled;
-    const { selector, hasText, hasNonEmptyText, hasCustom } = optCondition(query, specs);
+    const { selector, selectorAsFirstChild, hasText, hasNonEmptyText, hasCustom } = optCondition(query, specs);
     if (childNode == null) {
         if (hasText) {
             if (nodeEnabled) {
@@ -47,7 +48,7 @@ childNode, specs, depth, mode) {
     }
     if (childNode.is(childNode.TEXT_NODE)) {
         if (hasNonEmptyText) {
-            if (childNode.isWhitespace()) {
+            if (isInterElementWhitespace(childNode.raw)) {
                 if (nodeEnabled) {
                     nodeLog('<#nonEmptyText>.matches(%s) => WHITESPACE (rejected)', query);
                 }
@@ -85,7 +86,7 @@ childNode, specs, depth, mode) {
                 hint: {},
             };
         }
-        if (childNode.isWhitespace()) {
+        if (isInterElementWhitespace(childNode.raw)) {
             if (nodeEnabled) {
                 nodeLog('<#text>.matches(%s) => WHITESPACE', query);
             }
@@ -135,7 +136,14 @@ childNode, specs, depth, mode) {
                 hint: {},
             };
         }
-        const result = matches(selector, childNode, specs, mode);
+        let result = matches(selector, childNode, specs, mode);
+        // The siblings are looked at only for an element that the rest does not take.
+        // The first child is that of the element's own parent, also inside a transparent
+        // element, whose content model is derived from its parent's: `style` in
+        // `<div><p></p><noscript><style>` is the first child of the noscript.
+        if (!result.matched && selectorAsFirstChild != null && isContentModelFirstChild(childNode)) {
+            result = matches(selectorAsFirstChild, childNode, specs, mode);
+        }
         if (nodeEnabled) {
             nodeLog('%s.matches(%s) => %s', childNode.raw, query, result.matched);
         }
@@ -203,6 +211,10 @@ childNode, specs, depth, mode) {
  *
  * The `'pretended'` criterion is the one `MLElement.isCustomElement` gives a
  * `:model()` selector; change them together.
+ *
+ * What a component renders is not known only when no pretender resolved it, and
+ * a web component renders as itself: `MLElement#isUnresolvedComponent` is the narrower
+ * criterion, which `start` uses to leave the components out of the evaluation.
  */
 function isTreatedAsCustom(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -220,18 +232,21 @@ element, mode) {
 const conditionWithoutSpecs = {
     '#custom': {
         selector: '#custom',
+        selectorAsFirstChild: null,
         hasCustom: true,
         hasText: false,
         hasNonEmptyText: false,
     },
     '#text': {
         selector: '#text',
+        selectorAsFirstChild: null,
         hasCustom: false,
         hasText: true,
         hasNonEmptyText: false,
     },
     '#nonEmptyText': {
         selector: '#nonEmptyText',
+        selectorAsFirstChild: null,
         hasCustom: false,
         hasText: false,
         hasNonEmptyText: true,
@@ -271,7 +286,9 @@ function optCondition(query, specs) {
     let hasCustom = false;
     let hasText = false;
     let hasNonEmptyText = false;
-    const selector = query.replace(/^:model\(([^)]+)\)|^#([a-z-]+)/, (_, $model, _model) => {
+    let asFirstChild = null;
+    const categoryPattern = /^:model\(([^)]+)\)|^#([a-z-]+)/;
+    const selector = query.replace(categoryPattern, (_, $model, _model) => {
         const tag = `#${$model ?? _model}`;
         if (tag === '#nonEmptyText') {
             hasNonEmptyText = true;
@@ -282,6 +299,7 @@ function optCondition(query, specs) {
             throw new Error(`${$model ?? _model} is empty`);
         }
         const selectors = [];
+        const firstChildBases = [];
         for (const selector of _selectors) {
             if (selector === '#custom') {
                 hasCustom = true;
@@ -291,12 +309,21 @@ function optCondition(query, specs) {
                 hasText = true;
                 continue;
             }
+            const firstChildBase = contentModelFirstChildBase(selector);
+            if (firstChildBase != null) {
+                firstChildBases.push(firstChildBase);
+                continue;
+            }
             selectors.push(selector);
         }
+        if (firstChildBases.length > 0) {
+            asFirstChild = `:is(${firstChildBases.join(',')})`;
+        }
         return `:is(${selectors.join(',')})`;
     });
     const result = {
         selector,
+        selectorAsFirstChild: asFirstChild == null ? null : query.replace(categoryPattern, () => asFirstChild ?? ''),
         hasCustom,
         hasText,
         hasNonEmptyText,

package/lib/permitted-contents/represent-transparent-nodes.js

@@ -1,8 +1,9 @@
+import { isInterElementWhitespace } from '@markuplint/selector';
 import { resolveContentModel } from './content-model.js';
 import { cmLog } from './debug.js';
 import { order } from './order.js';
 import { expandChildren, getContentOwner, getSlotContent } from './slot-content.js';
-import { Collection, isTransparent, matches } from './utils.js';
+import { Collection, isComment, isTransparent, matches } from './utils.js';
 /**
  * A map tracking child nodes that are currently being evaluated through
  * a transparent content model. Used to prevent infinite recursion and
@@ -97,78 +98,13 @@ childNodes, rules, specs, options, mode) {
             }
             continue;
         }
-        // A component whose children sit inside an inner wrapper element (or one of
-        // several) cannot be looked through as transparent content: the children
-        // belong to the wrapper, not to the outermost element that is being matched.
-        const childSlot = getSlotContent(childNode, mode);
-        if (childSlot && (!childSlot.wrapper || getContentOwner(childNode, mode) !== childNode)) {
+        const branchGroups = transparentBranchGroups(childNode, rules, specs, options, mode);
+        if (branchGroups == null) {
             for (const p of patterns) {
                 p.push(childNode);
             }
             continue;
         }
-        const models = resolveContentModel(childNode, rules, specs, mode);
-        if (models == null || typeof models === 'boolean') {
-            for (const p of patterns) {
-                p.push(childNode);
-            }
-            continue;
-        }
-        const noTransparentModels = models.filter(m => !isTransparent(m));
-        if (noTransparentModels.length === models.length) {
-            for (const p of patterns) {
-                p.push(childNode);
-            }
-            continue;
-        }
-        const childNodesPatterns = options.evaluateConditionalChildNodes
-            ? childNode.conditionalChildNodes().map(childNodes => [...expandChildren(childNode, [...childNodes], mode)])
-            : [
-                [...expandChildren(childNode, [...childNode.childNodes], mode)].filter(child => !(child.is(child.TEXT_NODE) && child.isWhitespace())),
-            ];
-        const branchGroups = [];
-        for (const branchChildNodes of childNodesPatterns) {
-            const collection = new Collection([...branchChildNodes]);
-            let unmatched;
-            if (noTransparentModels.length > 0) {
-                const result = order(noTransparentModels, collection.unmatched, rules, specs, options, Number.POSITIVE_INFINITY, mode);
-                unmatched = result.unmatched;
-            }
-            else {
-                unmatched = collection.unmatched;
-            }
-            const transparent = models.find(m => isTransparent(m));
-            if (!transparent || !isTransparent(transparent)) {
-                throw new Error('Unreachable code');
-            }
-            const branchChildren = [];
-            for (const _child of unmatched) {
-                const child = _child;
-                if (transparentMode.has(child)) {
-                    continue;
-                }
-                transparentMode.set(child, true);
-                if (child.is(child.ELEMENT_NODE)) {
-                    const transparentCondMatched = matches(transparent.transparent, child, specs, mode);
-                    if (!transparentCondMatched.matched) {
-                        branchChildren.push({
-                            type: 'TRANSPARENT_MODEL_DISALLOWS',
-                            matched: [],
-                            unmatched: [childNode],
-                            zeroMatch: false,
-                            query: transparent.transparent,
-                            hint: {
-                                not: transparentCondMatched.not,
-                                transparent: childNode,
-                            },
-                        });
-                        continue;
-                    }
-                }
-                branchChildren.push(child);
-            }
-            branchGroups.push(branchChildren);
-        }
         // The transparent element itself is still a child of the current parent
         // and must be evaluated against the parent's own content model (e.g., a
         // `<button>` must reject an `<a href>` descendant even though `<a>`'s
@@ -223,3 +159,99 @@ childNodes, rules, specs, options, mode) {
     });
     return result;
 }
+/**
+ * The children that a transparent element stands for in its parent, one group per
+ * conditional branch, or `null` when the element is not looked through (its content
+ * model has no transparent part, or it is a component whose children belong to an
+ * inner wrapper).
+ *
+ * A child that is itself a transparent element is followed by the children it
+ * stands for, so that `<span><ins><ins><div>` puts the `<div>` in the `<span>`: the
+ * HTML Standard derives the content model of a transparent element from its parent
+ * again for each transparent element in which the content finds itself.
+ *
+ * > In some cases, where transparent elements are nested in each other, the process
+ * > has to be applied iteratively.
+ *
+ * @see https://html.spec.whatwg.org/multipage/dom.html#transparent-content-models
+ *
+ * The branches of a nested transparent element are merged into each branch of the
+ * outer one, the same over-approximation as the fallback documented on
+ * {@link MAX_PATTERNS}.
+ */
+function transparentBranchGroups(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+childNode, rules, specs, options, mode) {
+    // A component whose children sit inside an inner wrapper element (or one of
+    // several) cannot be looked through as transparent content: the children
+    // belong to the wrapper, not to the outermost element that is being matched.
+    const childSlot = getSlotContent(childNode, mode);
+    if (childSlot && (!childSlot.wrapper || getContentOwner(childNode, mode) !== childNode)) {
+        return null;
+    }
+    const models = resolveContentModel(childNode, rules, specs, mode);
+    if (models == null || typeof models === 'boolean') {
+        return null;
+    }
+    const noTransparentModels = models.filter(m => !isTransparent(m));
+    if (noTransparentModels.length === models.length) {
+        return null;
+    }
+    const childNodesPatterns = options.evaluateConditionalChildNodes
+        ? childNode
+            .conditionalChildNodes()
+            .map(childNodes => [...expandChildren(childNode, [...childNodes], mode)].filter(child => !isComment(child)))
+        : [
+            [...expandChildren(childNode, [...childNode.childNodes], mode)].filter(child => !isComment(child) && !(child.is(child.TEXT_NODE) && isInterElementWhitespace(child.raw))),
+        ];
+    const branchGroups = [];
+    for (const branchChildNodes of childNodesPatterns) {
+        const collection = new Collection([...branchChildNodes]);
+        let unmatched;
+        if (noTransparentModels.length > 0) {
+            const result = order(noTransparentModels, collection.unmatched, rules, specs, options, Number.POSITIVE_INFINITY, mode);
+            unmatched = result.unmatched;
+        }
+        else {
+            unmatched = collection.unmatched;
+        }
+        const transparent = models.find(m => isTransparent(m));
+        if (!transparent || !isTransparent(transparent)) {
+            throw new Error('Unreachable code');
+        }
+        const branchChildren = [];
+        for (const _child of unmatched) {
+            const child = _child;
+            if (transparentMode.has(child)) {
+                continue;
+            }
+            transparentMode.set(child, true);
+            if (child.is(child.ELEMENT_NODE)) {
+                const transparentCondMatched = matches(transparent.transparent, child, specs, mode);
+                if (!transparentCondMatched.matched) {
+                    branchChildren.push({
+                        type: 'TRANSPARENT_MODEL_DISALLOWS',
+                        matched: [],
+                        unmatched: [childNode],
+                        zeroMatch: false,
+                        query: transparent.transparent,
+                        hint: {
+                            not: transparentCondMatched.not,
+                            transparent: childNode,
+                        },
+                    });
+                    continue;
+                }
+                branchChildren.push(child);
+                const nested = transparentBranchGroups(child, rules, specs, options, mode);
+                if (nested != null) {
+                    branchChildren.push(...nested.flat());
+                }
+                continue;
+            }
+            branchChildren.push(child);
+        }
+        branchGroups.push(branchChildren);
+    }
+    return branchGroups;
+}

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

@@ -24,7 +24,8 @@ export declare function getContentOwner<T extends RuleConfigValue, O extends Pla
  * The children of `el` to validate: the nodes given at the usage site, passed
  * through the pretender's `contents` when it declares any, with the children of
  * fragment pretenders (`element: '#fragment'`) expanded in place because such a
- * component contributes its contents directly to its parent.
+ * component contributes its contents directly to its parent. What the framework
+ * moves to the `<head>` (`movedToHead` of the spec) is not a child of `el` in the DOM.
  */
 export declare function expandChildren<T extends RuleConfigValue, O extends PlainData>(el: Element<T, O>, given: readonly ChildNode<T, O>[], mode: Mode): readonly ChildNode<T, O>[];
 /**
@@ -33,6 +34,22 @@ export declare function expandChildren<T extends RuleConfigValue, O extends Plai
  * a fragment pretender among its children (which stands in the parent).
  */
 export declare function isContentMutable<T extends RuleConfigValue, O extends PlainData>(el: Element<T, O>, mode: Mode): boolean;
+/**
+ * Whether a child of `el` that the content model reads is a block of a preprocessor or a `slot`
+ * (`mayRenderUnknownChildren`): a required child that is missing may be what it renders.
+ * Only the children are looked at (the children of a fragment pretender included, as the content
+ * model reads them): what a descendant renders is not a child of `el`.
+ *
+ * A component that no pretender resolved is not looked at here: `start` leaves it out of each
+ * conditional branch that has one, and drops the missing children of that branch only.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param el - The element whose children are looked at
+ * @param mode - Which identity of `el` the content model is read for
+ * @returns True if a child may stand for children that are not known
+ */
+export declare function hasMutableChildNodes<T extends RuleConfigValue, O extends PlainData>(el: Element<T, O>, mode: Mode): boolean;
 /**
  * A violation on an element that only the pretender renders (`contents`) is reported
  * on the component that renders it: the element does not exist in the source.

package/lib/permitted-contents/slot-content.js

@@ -1,3 +1,4 @@
+import { mayRenderUnknownChildren } from '../helpers.js';
 /**
  * Returns the slot-content description of a pretended component, which exists
  * only in `'pretended'` mode: the `'origin'` mode evaluates user tag rules keyed
@@ -34,14 +35,40 @@ el, mode) {
     }
     return el;
 }
+/**
+ * Whether the framework moves `child` out of `parent`: the spec of the framework lists the elements
+ * it places in the `<head>` wherever they are written (`movedToHead`), so what `parent` contains in
+ * the DOM does not include them. The `<head>` itself keeps them: that is where they are placed.
+ *
+ * @see MLMLSpec.movedToHead in `@markuplint/ml-spec`
+ */
+function isMovedToHead(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+parent, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+child) {
+    const selectors = parent.ownerMLDocument.specs.movedToHead;
+    if (!selectors || !child.is(child.ELEMENT_NODE) || parent.localName === 'head') {
+        return false;
+    }
+    return selectors.some(selector => child.matches(selector));
+}
 /**
  * The children of `el` to validate: the nodes given at the usage site, passed
  * through the pretender's `contents` when it declares any, with the children of
  * fragment pretenders (`element: '#fragment'`) expanded in place because such a
- * component contributes its contents directly to its parent.
+ * component contributes its contents directly to its parent. What the framework
+ * moves to the `<head>` (`movedToHead` of the spec) is not a child of `el` in the DOM.
  */
 export function expandChildren(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, given, mode) {
+    // Only here, not in the expansion of a fragment: what a fragment contributes belongs to `el`, so
+    // it is `el` that decides whether it is moved (the `<head>` keeps it), not the fragment.
+    return fillAndExpand(el, given, mode).filter(child => !isMovedToHead(el, child));
+}
+function fillAndExpand(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, given, mode) {
     const slotContent = getSlotContent(el, mode);
     const children = slotContent ? slotContent.fill(given) : given;
@@ -60,6 +87,26 @@ el, mode) {
     }
     return [...el.childNodes].some(child => isFragmentPretender(child, mode) && isContentMutable(child, mode));
 }
+/**
+ * Whether a child of `el` that the content model reads is a block of a preprocessor or a `slot`
+ * (`mayRenderUnknownChildren`): a required child that is missing may be what it renders.
+ * Only the children are looked at (the children of a fragment pretender included, as the content
+ * model reads them): what a descendant renders is not a child of `el`.
+ *
+ * A component that no pretender resolved is not looked at here: `start` leaves it out of each
+ * conditional branch that has one, and drops the missing children of that branch only.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param el - The element whose children are looked at
+ * @param mode - Which identity of `el` the content model is read for
+ * @returns True if a child may stand for children that are not known
+ */
+export function hasMutableChildNodes(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+el, mode) {
+    return expandChildren(el, [...el.getPureChildNodes()], mode).some(child => mayRenderUnknownChildren(child, false));
+}
 function isFragmentPretender(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node, mode) {
@@ -71,7 +118,7 @@ node, mode) {
 function expandFragment(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node, mode) {
-    return isFragmentPretender(node, mode) ? expandChildren(node, [...node.childNodes], mode) : [node];
+    return isFragmentPretender(node, mode) ? fillAndExpand(node, [...node.childNodes], mode) : [node];
 }
 /**
  * A violation on an element that only the pretender renders (`contents`) is reported

package/lib/permitted-contents/start.d.ts

@@ -10,10 +10,17 @@ import type { ReadonlyDeep } from 'type-fest';
  * When `options.evaluateConditionalChildNodes` is enabled, all conditional branches
  * (e.g., from template directives) are evaluated independently.
  *
+ * A component that no pretender resolved (`MLElement#isUnresolvedComponent`) renders something that is
+ * not known: it may be the element that the content model asks for, or stand for several. With
+ * `ignoreUnresolvedComponents` the children are evaluated without such components, and only what holds
+ * whatever they render is kept ({@link holdsWhateverIsRendered}). Without it they are evaluated as
+ * written, by the name of the component (`isTreatedAsCustom` of `matches-selector.ts`).
+ *
  * @param contents - The content model definition: `false` for empty, `true` for any, or an array of patterns.
  * @param el - The parent element whose children are being validated.
  * @param specs - The resolved spec data for content model lookups.
  * @param options - Validation behavior options.
+ * @param ignoreUnresolvedComponents - Whether to evaluate the children without the components that no pretender resolved.
  * @returns An array of content model results describing any violations found.
  */
-export declare function start(contents: ReadonlyDeep<ContentModel['contents']>, el: Element, rules: readonly TagRule[], specs: Specs, options: Options, mode: Mode): ContentModelResult[];
+export declare function start(contents: ReadonlyDeep<ContentModel['contents']>, el: Element, rules: readonly TagRule[], specs: Specs, options: Options, mode: Mode, ignoreUnresolvedComponents?: boolean): ContentModelResult[];

package/lib/permitted-contents/start.js

@@ -1,6 +1,8 @@
+import { isInterElementWhitespace } from '@markuplint/selector';
 import { order } from './order.js';
 import { representTransparentNodes } from './represent-transparent-nodes.js';
 import { expandChildren } from './slot-content.js';
+import { isComment } from './utils.js';
 /**
  * Entry point for validating an element's child nodes against a content model definition.
  * Handles the three forms of content model: `false` (no content allowed), `true` (any content
@@ -10,25 +12,42 @@ import { expandChildren } from './slot-content.js';
  * When `options.evaluateConditionalChildNodes` is enabled, all conditional branches
  * (e.g., from template directives) are evaluated independently.
  *
+ * A component that no pretender resolved (`MLElement#isUnresolvedComponent`) renders something that is
+ * not known: it may be the element that the content model asks for, or stand for several. With
+ * `ignoreUnresolvedComponents` the children are evaluated without such components, and only what holds
+ * whatever they render is kept ({@link holdsWhateverIsRendered}). Without it they are evaluated as
+ * written, by the name of the component (`isTreatedAsCustom` of `matches-selector.ts`).
+ *
  * @param contents - The content model definition: `false` for empty, `true` for any, or an array of patterns.
  * @param el - The parent element whose children are being validated.
  * @param specs - The resolved spec data for content model lookups.
  * @param options - Validation behavior options.
+ * @param ignoreUnresolvedComponents - Whether to evaluate the children without the components that no pretender resolved.
  * @returns An array of content model results describing any violations found.
  */
 export function start(contents, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
-el, rules, specs, options, mode) {
+el, rules, specs, options, mode, ignoreUnresolvedComponents = false) {
     const givenPatterns = options.evaluateConditionalChildNodes
         ? el.conditionalChildNodes().map(childNodes => [...childNodes])
         : [[...el.childNodes]];
-    const childNodesPatterns = givenPatterns.map(given => {
-        const children = expandChildren(el, given, mode);
+    // A model that is `false` does not allow a component either: what it renders may be anything
+    const ignoresComponents = ignoreUnresolvedComponents && contents !== false && contents !== true;
+    const isIgnoredComponent = (child) => ignoresComponents && child.is(child.ELEMENT_NODE) && child.isUnresolvedComponent();
+    const expandedPatterns = givenPatterns.map(given => expandChildren(el, given, mode));
+    // Per pattern: a conditional branch without a component is evaluated as it is written
+    const hasIgnoredComponents = expandedPatterns.map(expanded => expanded.some(child => isIgnoredComponent(child)));
+    const childNodesPatterns = expandedPatterns.map(expanded => {
+        const children = expanded.filter(child => !isComment(child) && !isIgnoredComponent(child));
         return options.evaluateConditionalChildNodes
             ? [...children]
-            : children.filter(child => !(child.is(child.TEXT_NODE) && child.isWhitespace()));
+            : children.filter(child => !(child.is(child.TEXT_NODE) && isInterElementWhitespace(child.raw)));
+    });
+    return childNodesPatterns.flatMap((childNodes, index) => {
+        const results = evaluate(childNodes);
+        return hasIgnoredComponents[index] ? results.filter(result => holdsWhateverIsRendered(result)) : results;
     });
-    return childNodesPatterns.flatMap(childNodes => {
+    function evaluate(childNodes) {
         if (contents === false) {
             if (childNodes.length > 0) {
                 return [
@@ -80,5 +99,19 @@ el, rules, specs, options, mode) {
                 })),
             ];
         });
-    });
+    }
+}
+/**
+ * Whether a violation found without the components that no pretender resolved holds whatever
+ * they render.
+ *
+ * A component may render the child that is missing, so a missing child is not one. An element
+ * that the content model does not take is (`<div>` in `<ul><Item /><div></div></ul>`, the second
+ * `<title>` in `<head><Meta /><title /><title /></head>`): `order` reports it only after it has
+ * consumed every entry that it can, and a component adds nodes without moving or removing the ones
+ * that are written. The order is not reported either: when the elements are out of order the
+ * entry that comes first is missing, which a component may render (`<dl><Term /><dd></dd></dl>`).
+ */
+function holdsWhateverIsRendered(result) {
+    return result.type !== 'MISSING_NODE_REQUIRED' && result.type !== 'MISSING_NODE_ONE_OR_MORE';
 }

package/lib/permitted-contents/utils.d.ts

@@ -1,6 +1,17 @@
 import type { ChildNode, Hints, MissingNodeReason, Mode, RepeatSign, Specs } from './types.js';
 import type { PermittedContentPattern, PermittedContentChoice, PermittedContentOneOrMore, PermittedContentOptional, PermittedContentRequire, PermittedContentTransparent, PermittedContentZeroOrMore, Model } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Whether a child node is a comment, which a content model does not see.
+ * Without this, a comment is matched like an element and takes the place of
+ * one the model requires (`<html><!-- c --><head>` leaves `head` unmatched).
+ *
+ * @param node - The child node to test.
+ * @returns True if the node is a comment node.
+ * @see https://html.spec.whatwg.org/multipage/dom.html#content-models
+ * > Inter-element whitespace, comment nodes, and processing instruction nodes must be ignored when establishing whether an element's contents match the element's content model or not
+ */
+export declare function isComment(node: ChildNode): boolean;
 /**
  * Determines whether a given value is a terminal model (a selector string or an array
  * of selector strings) rather than a nested array of content model patterns.

package/lib/permitted-contents/utils.js

@@ -1,6 +1,21 @@
 import { createSelector } from '@markuplint/selector';
 import { bgGreen, green, bgRed, bgBlue, blue, bgMagenta, cyan } from './debug.js';
 import { transparentMode } from './represent-transparent-nodes.js';
+/**
+ * Whether a child node is a comment, which a content model does not see.
+ * Without this, a comment is matched like an element and takes the place of
+ * one the model requires (`<html><!-- c --><head>` leaves `head` unmatched).
+ *
+ * @param node - The child node to test.
+ * @returns True if the node is a comment node.
+ * @see https://html.spec.whatwg.org/multipage/dom.html#content-models
+ * > Inter-element whitespace, comment nodes, and processing instruction nodes must be ignored when establishing whether an element's contents match the element's content model or not
+ */
+export function isComment(
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
+node) {
+    return node.is(node.COMMENT_NODE);
+}
 /**
  * Determines whether a given value is a terminal model (a selector string or an array
  * of selector strings) rather than a nested array of content model patterns.