@markuplint/rules 4.11.2 → 5.0.0-alpha.0

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

@@ -1,8 +1,85 @@
 import { getContentModel } from '@markuplint/ml-spec';
-import { branchesToPatterns } from '@markuplint/shared';
 import { order } from './order.js';
 import { Collection, 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
+ * to enable special handling in error messages and debug output.
+ */
 export const transparentMode = new Map();
+/**
+ * Maximum number of patterns to generate before falling back to a
+ * conservative all-children-merged approach. Prevents exponential
+ * blowup when many conditional transparent elements are siblings.
+ *
+ * ### Rationale
+ *
+ * When N transparent elements each have K conditional branches (e.g.,
+ * `v-if`/`v-else`), the exact cross-product yields K^N patterns.
+ * With K=2 and N=10, this is 2^10 = 1024 — still manageable.
+ * At N=11 (2^11 = 2048) the cap triggers, switching to a
+ * conservative fallback that merges all branch children into every
+ * pattern. This keeps runtime linear while covering most real-world
+ * conditional structures.
+ *
+ * ### Fallback precision
+ *
+ * When the cap is exceeded, the fallback produces an
+ * **over-approximation**: all children from all branches are included
+ * in every pattern. This may cause false negatives (valid violations
+ * go undetected because the merged pattern appears to satisfy the
+ * content model) but will never cause false positives (spurious
+ * violations are not introduced). In practice, HTML documents rarely
+ * exceed 10 conditional transparent siblings, so the cap is
+ * transparent to most users.
+ *
+ * @see https://github.com/markuplint/markuplint/issues/3249
+ */
+const MAX_PATTERNS = 1024;
+/**
+ * Resolves transparent content model elements by replacing them with their
+ * children for validation purposes. In HTML, elements like `<a>`, `<ins>`, and `<del>`
+ * have transparent content models, meaning their children must be valid in the
+ * parent's content model as if the transparent element were not present.
+ *
+ * This function:
+ * 1. Identifies child elements with transparent content models.
+ * 2. Filters out children that match non-transparent parts of the element's content model.
+ * 3. Replaces the transparent element with its remaining (unmatched) children.
+ * 4. Validates that each remaining child satisfies the transparent model's condition selector.
+ * 5. Recursively resolves parent-level transparent nodes to propagate errors up the tree.
+ * 6. Builds patterns incrementally, capping cross-products to avoid exponential blowup.
+ *
+ * ### Algorithm — incremental pattern building
+ *
+ * Patterns are built incrementally as each child node is visited:
+ *
+ * - **Non-transparent child**: appended to every existing pattern.
+ *   Pattern count stays the same.
+ * - **Single-branch transparent child** (non-conditional, or
+ *   `evaluateConditionalChildNodes` disabled): all unmatched children
+ *   are spread into every pattern. Pattern count stays the same.
+ * - **Multi-branch transparent child** (conditional, e.g. `v-if`/`v-else`):
+ *   a cross-product of existing patterns × branch groups is computed,
+ *   capped at {@link MAX_PATTERNS}. If the cap would be exceeded, a
+ *   conservative fallback merges all branch children into every pattern.
+ *
+ * ### Complexity
+ *
+ * - **Previous algorithm** (`branchesToPatterns` Cartesian product):
+ *   O(K^N) time and space, where N = number of transparent elements,
+ *   K = average branch count per element. 12 elements with 2 children
+ *   each produced 4096 patterns and took 30+ seconds.
+ * - **Current algorithm**: O(N × K × min(|patterns|, MAX_PATTERNS))
+ *   time; O(MAX_PATTERNS × P) space where P = average pattern length.
+ *   The same 12-element case now produces 1 pattern in <100 ms.
+ *
+ * @param childNodes - The child nodes of the element being validated, some of which may be transparent.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @returns An array of possible transparent node resolutions, each with flattened nodes and accumulated errors.
+ * @see https://github.com/markuplint/markuplint/issues/3249
+ */
 export function representTransparentNodes(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNodes, specs, options) {
@@ -10,28 +87,34 @@ childNodes, specs, options) {
     const parentResults = parentElement
         ? representTransparentNodes([parentElement], specs, options)
         : [{ nodes: [], errors: [] }];
-    const branches = [];
+    let patterns = [[]];
     for (const childNode of childNodes) {
         if (!childNode.is(childNode.ELEMENT_NODE)) {
-            branches.push(childNode);
+            for (const p of patterns) {
+                p.push(childNode);
+            }
             continue;
         }
         const models = getContentModel(childNode, specs.specs);
         if (models == null || typeof models === 'boolean') {
-            branches.push(childNode);
+            for (const p of patterns) {
+                p.push(childNode);
+            }
             continue;
         }
         const noTransparentModels = models.filter(m => !isTransparent(m));
         if (noTransparentModels.length === models.length) {
-            branches.push(childNode);
+            for (const p of patterns) {
+                p.push(childNode);
+            }
             continue;
         }
         const childNodesPatterns = options.evaluateConditionalChildNodes
             ? childNode.conditionalChildNodes().map(childNodes => [...childNodes])
             : [[...childNode.childNodes].filter(child => !(child.is(child.TEXT_NODE) && child.isWhitespace()))];
-        const representPattern = [];
-        for (const childNodes of childNodesPatterns) {
-            const collection = new Collection([...childNodes]);
+        const branchGroups = [];
+        for (const branchChildNodes of childNodesPatterns) {
+            const collection = new Collection([...branchChildNodes]);
             let unmatched;
             if (noTransparentModels.length > 0) {
                 const result = order(noTransparentModels, collection.unmatched, specs, options, Number.POSITIVE_INFINITY);
@@ -44,6 +127,7 @@ childNodes, specs, options) {
             if (!transparent || !isTransparent(transparent)) {
                 throw new Error('Unreachable code');
             }
+            const branchChildren = [];
             for (const _child of unmatched) {
                 const child = _child;
                 if (transparentMode.has(child)) {
@@ -53,7 +137,7 @@ childNodes, specs, options) {
                 if (child.is(child.ELEMENT_NODE)) {
                     const transparentCondMatched = matches(transparent.transparent, child, specs);
                     if (!transparentCondMatched.matched) {
-                        representPattern.push({
+                        branchChildren.push({
                             type: 'TRANSPARENT_MODEL_DISALLOWS',
                             matched: [],
                             unmatched: [childNode],
@@ -67,12 +151,35 @@ childNodes, specs, options) {
                         continue;
                     }
                 }
-                representPattern.push(child);
+                branchChildren.push(child);
+            }
+            branchGroups.push(branchChildren);
+        }
+        if (branchGroups.every(g => g.length === 0)) {
+            continue;
+        }
+        if (branchGroups.length === 1) {
+            const singleGroup = branchGroups[0];
+            for (const p of patterns) {
+                p.push(...singleGroup);
+            }
+        }
+        else if (patterns.length * branchGroups.length <= MAX_PATTERNS) {
+            const newPatterns = [];
+            for (const p of patterns) {
+                for (const group of branchGroups) {
+                    newPatterns.push([...p, ...group]);
+                }
+            }
+            patterns = newPatterns;
+        }
+        else {
+            const allChildren = branchGroups.flat();
+            for (const p of patterns) {
+                p.push(...allChildren);
             }
         }
-        branches.push(representPattern);
     }
-    const patterns = branchesToPatterns(branches);
     const result = parentResults.flatMap(parentResult => {
         const patternResults = patterns.map(pattern => {
             const nodes = pattern.filter((node) => 'nodeName' in node);

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

@@ -2,12 +2,18 @@ import type { ContentModelResult, Element, Options, Specs } from './types.js';
 import type { ContentModel } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
- * Check start
+ * 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
+ * allowed), or an ordered pattern array. For pattern arrays, transparent content model nodes
+ * are first resolved, then each resulting pattern of child nodes is validated via `order`.
  *
- * @param contents
- * @param el
- * @param specs
- * @param options
- * @returns
+ * When `options.evaluateConditionalChildNodes` is enabled, all conditional branches
+ * (e.g., from template directives) are evaluated independently.
+ *
+ * @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.
+ * @returns An array of content model results describing any violations found.
  */
 export declare function start(contents: ReadonlyDeep<ContentModel['contents']>, el: Element, specs: Specs, options: Options): ContentModelResult[];

package/lib/permitted-contents/start.js

@@ -1,13 +1,19 @@
 import { order } from './order.js';
 import { representTransparentNodes } from './represent-transparent-nodes.js';
 /**
- * Check start
+ * 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
+ * allowed), or an ordered pattern array. For pattern arrays, transparent content model nodes
+ * are first resolved, then each resulting pattern of child nodes is validated via `order`.
  *
- * @param contents
- * @param el
- * @param specs
- * @param options
- * @returns
+ * When `options.evaluateConditionalChildNodes` is enabled, all conditional branches
+ * (e.g., from template directives) are evaluated independently.
+ *
+ * @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.
+ * @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

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

@@ -1,2 +1,14 @@
 import type { ChildNode, Result } from './types.js';
+/**
+ * Handles the transparent content model pattern by passing all child nodes
+ * through as matched. In HTML, a transparent element inherits the content model
+ * of its parent, so its children are validated against the parent's model instead.
+ *
+ * If the element is a component root (has no grandparent element), all children
+ * are treated as matched. Otherwise, validation is deferred to the parent's
+ * content model processing.
+ *
+ * @param childNodes - The child nodes to evaluate under the transparent model.
+ * @returns A result indicating all children are matched (validation deferred to parent).
+ */
 export declare function transparent(childNodes: readonly ChildNode[]): Result;

package/lib/permitted-contents/transparent.js

@@ -1,5 +1,17 @@
 import { cmLog } from './debug.js';
 const transparentLog = cmLog.extend('transparent');
+/**
+ * Handles the transparent content model pattern by passing all child nodes
+ * through as matched. In HTML, a transparent element inherits the content model
+ * of its parent, so its children are validated against the parent's model instead.
+ *
+ * If the element is a component root (has no grandparent element), all children
+ * are treated as matched. Otherwise, validation is deferred to the parent's
+ * content model processing.
+ *
+ * @param childNodes - The child nodes to evaluate under the transparent model.
+ * @returns A result indicating all children are matched (validation deferred to parent).
+ */
 export function transparent(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNodes) {

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

@@ -1,8 +1,19 @@
 import type { Element as _Element, ChildNode as _ChildNode } from '@markuplint/ml-core';
 import type { ContentModel, MLMLSpec } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * An element node parameterized with the permitted-contents rule's TagRule and Options.
+ */
 export type Element = _Element<TagRule[], Options>;
+/**
+ * A child node parameterized with the permitted-contents rule's TagRule and Options.
+ */
 export type ChildNode = _ChildNode<TagRule[], Options>;
+/**
+ * A subset of the full ML spec containing only the fields needed
+ * for content model validation: citation references, global definitions,
+ * and per-element content model specifications.
+ */
 export type Specs = {
     readonly cites: MLMLSpec['cites'];
     readonly def: MLMLSpec['def'];
@@ -13,12 +24,24 @@ export type Specs = {
         };
     }[];
 };
+/**
+ * The final result of content model validation for a single child node,
+ * indicating whether the node is permitted, missing, or unexpected
+ * within its parent element's content model.
+ */
 export type ContentModelResult = {
     type: MatchedReason | UnmatchedReason;
     scope: ChildNode;
     query: Result['query'];
     hint: Result['hint'];
 };
+/**
+ * An intermediate result produced during content model pattern matching.
+ * Tracks which child nodes were matched, which were unmatched, and
+ * provides diagnostic hints about the nature of a mismatch.
+ *
+ * @template T - Additional result type strings beyond the standard matched/unmatched reasons.
+ */
 export type Result<T extends string = MatchedReason> = {
     type: MatchedReason | UnmatchedReason | T;
     matched: ChildNode[];
@@ -27,6 +50,11 @@ export type Result<T extends string = MatchedReason> = {
     query: string;
     hint: Hints;
 };
+/**
+ * Diagnostic hints attached to a content model result, providing additional
+ * context for error reporting such as maximum allowed count, the offending
+ * node, or information about transparent model violations.
+ */
 export type Hints = {
     max?: number;
     not?: ChildNode;
@@ -36,21 +64,60 @@ export type Hints = {
         need?: string;
     };
 };
+/**
+ * Reasons indicating that a content model pattern successfully matched.
+ * `MATCHED` means one or more nodes matched; `MATCHED_ZERO` means the pattern
+ * matched vacuously (zero nodes consumed, but the pattern allows it).
+ */
 export type MatchedReason = 'MATCHED' | 'MATCHED_ZERO';
+/**
+ * Reasons indicating that a content model pattern did not match.
+ * Includes cases where content is disallowed entirely, an unexpected node
+ * was found, a transparent model forbids the node, or a required node is missing.
+ */
 export type UnmatchedReason = 'NOTHING' | 'UNEXPECTED_EXTRA_NODE' | 'TRANSPARENT_MODEL_DISALLOWS' | MissingNodeReason;
+/**
+ * Specific reasons for a missing node: either a required element is absent,
+ * or one-or-more occurrences are expected but none were found.
+ */
 export type MissingNodeReason = 'MISSING_NODE_REQUIRED' | 'MISSING_NODE_ONE_OR_MORE';
+/**
+ * A regular-expression-like repeat sign used to describe the quantifier
+ * of a content model pattern (e.g., `?` for optional, `+` for one-or-more,
+ * `*` for zero-or-more, or `{min,max}` for a specific range).
+ */
 export type RepeatSign = '' | '?' | '+' | '*' | `{${number},${number}}`;
+/**
+ * Describes a transparent content model element along with any additional
+ * CSS selector condition that must be satisfied for the transparency to apply.
+ */
 export type TransparentModel = {
     el: Element;
     additionalCondition: string;
 };
+/**
+ * A user-defined tag rule that associates an element tag name with
+ * its permitted content model definition, used to override or extend
+ * the built-in HTML spec content models.
+ */
 export type TagRule = {
     readonly tag: string;
 } & ReadonlyDeep<ContentModel>;
+/**
+ * Options for the permitted-contents rule that control validation behavior.
+ */
 export type Options = {
+    /**
+     * When true, skips reporting missing-node errors on elements that
+     * have mutable children (e.g., elements whose children may be
+     * dynamically injected by a framework or template engine).
+     */
     readonly ignoreHasMutableChildren: boolean;
     /**
      * @experimental
+     * When true, evaluates conditional child node branches (e.g., from
+     * template directives like `v-if`) to validate each possible branch
+     * against the content model.
      */
     readonly evaluateConditionalChildNodes: boolean;
 };

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

@@ -1,7 +1,26 @@
 import type { ChildNode, Hints, MissingNodeReason, 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';
+/**
+ * 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.
+ * Distinguishes between `Model` (leaf-level selectors) and `PermittedContentPattern[]`
+ * (structural pattern arrays that require further recursive evaluation).
+ *
+ * @param model - The value to check, either a terminal model or a nested pattern array.
+ * @returns True if the value is a terminal model (string or string array), false if it is a pattern array.
+ */
 export declare function isModel(model: ReadonlyDeep<Model | PermittedContentPattern[]>): model is ReadonlyDeep<Model>;
+/**
+ * Tests whether a child node matches a CSS selector string using the markuplint
+ * selector engine. Returns whether the node matched and, if not, the deepest
+ * unmatched descendant node for diagnostic purposes.
+ *
+ * @param selector - The CSS selector string to test against.
+ * @param node - The child node to test.
+ * @param specs - The spec data passed to the selector engine for attribute resolution.
+ * @returns An object with `matched: true` if the node matches, or `matched: false` with an optional `not` node.
+ */
 export declare function matches(selector: string, node: ChildNode, specs: Specs): {
     matched: boolean;
     not?: undefined;
@@ -9,12 +28,62 @@ export declare function matches(selector: string, node: ChildNode, specs: Specs)
     matched: boolean;
     not: ChildNode | undefined;
 };
+/**
+ * Type guard that checks whether a content model pattern is a "require" pattern,
+ * indicating one or more required occurrences of a specific element or model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `require` property.
+ */
 export declare function isRequire(content: ReadonlyDeep<PermittedContentPattern>): content is ReadonlyDeep<PermittedContentRequire>;
+/**
+ * Type guard that checks whether a content model pattern is an "optional" pattern,
+ * indicating zero or one occurrences of a specific element or model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has an `optional` property.
+ */
 export declare function isOptional(content: ReadonlyDeep<PermittedContentPattern>): content is ReadonlyDeep<PermittedContentOptional>;
+/**
+ * Type guard that checks whether a content model pattern is a "oneOrMore" pattern,
+ * indicating one or more occurrences of a specific element or model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `oneOrMore` property.
+ */
 export declare function isOneOrMore(content: ReadonlyDeep<PermittedContentPattern>): content is ReadonlyDeep<PermittedContentOneOrMore>;
+/**
+ * Type guard that checks whether a content model pattern is a "zeroOrMore" pattern,
+ * indicating zero or more occurrences of a specific element or model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `zeroOrMore` property.
+ */
 export declare function isZeroOrMore(content: ReadonlyDeep<PermittedContentPattern>): content is ReadonlyDeep<PermittedContentZeroOrMore>;
+/**
+ * Type guard that checks whether a content model pattern is a "choice" pattern,
+ * representing an alternation between multiple possible content model branches.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `choice` property.
+ */
 export declare function isChoice(content: ReadonlyDeep<PermittedContentPattern>): content is ReadonlyDeep<PermittedContentChoice>;
+/**
+ * Type guard that checks whether a content model pattern is a "transparent" pattern,
+ * indicating the element inherits its parent's content model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `transparent` property.
+ */
 export declare function isTransparent(content: ReadonlyDeep<PermittedContentPattern>): content is ReadonlyDeep<PermittedContentTransparent>;
+/**
+ * Normalizes a quantified content model pattern (require, optional, oneOrMore, or zeroOrMore)
+ * into a uniform representation with the inner model, minimum count, maximum count,
+ * a regex-like repeat sign for debug display, and the appropriate missing-node error type.
+ *
+ * @param pattern - A quantified content model pattern to normalize.
+ * @returns An object with `model`, `min`, `max`, `repeat` sign, and optional `missingType`.
+ */
 export declare function normalizeModel(pattern: ReadonlyDeep<PermittedContentRequire> | ReadonlyDeep<PermittedContentOptional> | ReadonlyDeep<PermittedContentOneOrMore> | ReadonlyDeep<PermittedContentZeroOrMore>): {
     model: ReadonlyDeep<PermittedContentPattern[] | Model>;
     min: number;
@@ -22,6 +91,15 @@ export declare function normalizeModel(pattern: ReadonlyDeep<PermittedContentReq
     repeat: RepeatSign;
     missingType: MissingNodeReason | undefined;
 };
+/**
+ * Merges two Hints objects, combining their properties and selecting the
+ * `missing` hint with the higher `barelyMatchedElements` count (i.e., the
+ * one closest to a successful match) for the most useful error diagnostics.
+ *
+ * @param a - The first hints object.
+ * @param b - The second hints object.
+ * @returns A merged hints object with undefined properties removed.
+ */
 export declare function mergeHints(a: Readonly<Hints>, b: Readonly<Hints>): Partial<{
     missing: Partial<{
         barelyMatchedElements?: number;
@@ -31,20 +109,102 @@ export declare function mergeHints(a: Readonly<Hints>, b: Readonly<Hints>): Part
     not?: ChildNode;
     transparent?: import("./types.js").Element;
 }>;
+/**
+ * Creates a shallow copy of an object with all `undefined` values removed.
+ * Used to produce clean hint objects for result reporting without
+ * extraneous undefined properties.
+ *
+ * @template T - The object type.
+ * @param object - The source object to clean.
+ * @returns A new object containing only the defined properties of the input.
+ */
 export declare function cleanObject<T extends object>(object: T): Partial<T>;
+/**
+ * Tracks matched and unmatched child nodes during content model validation.
+ * Provides operations for adding matched nodes, backtracking to a locked state,
+ * capping matches at a maximum count, and generating colored debug output.
+ *
+ * The collection maintains an ordered set of original nodes and partitions them
+ * into matched and unmatched sets as the validation algorithm progresses.
+ */
 export declare class Collection {
     #private;
+    /**
+     * Creates a new Collection from the given child nodes.
+     *
+     * @param origin - The initial list of child nodes to track.
+     */
     constructor(origin: readonly ChildNode[]);
+    /**
+     * Returns a copy of the currently matched nodes in insertion order.
+     */
     get matched(): ChildNode[];
+    /**
+     * Returns the number of currently matched nodes.
+     */
     get matchedCount(): number;
+    /**
+     * Returns a copy of all original nodes in their original order.
+     */
     get nodes(): ChildNode[];
+    /**
+     * Returns the nodes that have not yet been matched, preserving original order.
+     */
     get unmatched(): ChildNode[];
+    /**
+     * Adds nodes to the matched set. All nodes must belong to the original
+     * collection; external nodes will cause a ReferenceError.
+     *
+     * @param nodes - The child nodes to mark as matched.
+     * @returns True if the matched set grew (new nodes were added), false otherwise.
+     */
     addMatched(nodes: ChildNode[]): boolean;
+    /**
+     * Reverts the matched set to the last locked state, discarding
+     * any matches added since the last `lock()` call. Used for backtracking
+     * when a pattern match attempt fails after a zero-match.
+     */
     back(): void;
+    /**
+     * Saves the current matched set as a checkpoint that `back()` can
+     * revert to. Called after a successful backtrack recovery to preserve
+     * the known-good state.
+     */
     lock(): void;
+    /**
+     * Trims the matched set to at most `max` entries by removing
+     * the most recently added nodes beyond the limit. Used when the
+     * maximum occurrence count for a pattern is exceeded.
+     *
+     * @param max - The maximum number of matched nodes to retain.
+     */
     max(max: number): void;
+    /**
+     * Returns a colored string representation of all nodes for debug logging.
+     * Matched nodes are shown in green, locked nodes in bold green, unmatched
+     * extra nodes in red (when highlighted), and transparent-mode nodes in
+     * blue/cyan/magenta variants.
+     *
+     * @param highlightExtraNodes - When true, unmatched nodes are highlighted in red/magenta.
+     * @returns A formatted string like `[ <div>, <span>, <p> ]` with ANSI colors.
+     */
     toString(highlightExtraNodes?: boolean): string;
 }
+/**
+ * Error class representing an unsupported content model feature.
+ * Thrown when the validation engine encounters a pattern type or
+ * configuration that is not yet implemented.
+ */
 export declare class UnsupportedError extends Error {
 }
+/**
+ * Formats a content model (terminal model or pattern array) and its repeat sign
+ * into a regex-like string for debug logging output. Terminal selectors are
+ * rendered as `<selector>`, arrays of selectors as `(<s1>|<s2>)`, and
+ * nested patterns are recursively formatted.
+ *
+ * @param model - The model or pattern array to format.
+ * @param repeat - The quantifier sign to append (e.g., `+`, `*`, `?`, or `{m,n}`).
+ * @returns A human-readable regex-like string representation of the model.
+ */
 export declare function modelLog(model: ReadonlyDeep<Model | PermittedContentPattern[]>, repeat: RepeatSign): string;