@markuplint/rules 4.11.2 → 4.12.0

package/lib/permitted-contents/recursive-branch.d.ts

@@ -2,4 +2,21 @@ import type { SelectorResult } from './matches-selector.js';
 import type { ChildNode, Options, Specs } from './types.js';
 import type { PermittedContentPattern, Model } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Evaluates a model or nested pattern array against child nodes at the leaf level
+ * of the content model tree. If the input is a nested pattern array (not a terminal model),
+ * it recurses back into `order` for sequential evaluation. If it is a terminal model
+ * (a single selector string or an array of selector strings representing alternatives),
+ * it tests the first unmatched child node against each selector via `matchesSelector`.
+ *
+ * For array-of-selectors models, the selectors act as alternatives (logical OR): the first
+ * selector to match the child node produces the result.
+ *
+ * @param model - Either a terminal model (selector string or array of selector strings) or a nested pattern array.
+ * @param childNodes - The child nodes to validate against the model.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A selector result indicating whether the first unmatched child node matches the model.
+ */
 export declare function recursiveBranch(model: ReadonlyDeep<Model | PermittedContentPattern[]>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): SelectorResult;

package/lib/permitted-contents/recursive-branch.js

@@ -1,6 +1,23 @@
 import { matchesSelector } from './matches-selector.js';
 import { order } from './order.js';
 import { Collection, isModel } from './utils.js';
+/**
+ * Evaluates a model or nested pattern array against child nodes at the leaf level
+ * of the content model tree. If the input is a nested pattern array (not a terminal model),
+ * it recurses back into `order` for sequential evaluation. If it is a terminal model
+ * (a single selector string or an array of selector strings representing alternatives),
+ * it tests the first unmatched child node against each selector via `matchesSelector`.
+ *
+ * For array-of-selectors models, the selectors act as alternatives (logical OR): the first
+ * selector to match the child node produces the result.
+ *
+ * @param model - Either a terminal model (selector string or array of selector strings) or a nested pattern array.
+ * @param childNodes - The child nodes to validate against the model.
+ * @param specs - The resolved spec data for content model lookups.
+ * @param options - Validation behavior options.
+ * @param depth - The current recursion depth, used for debug logging and nested evaluation.
+ * @returns A selector result indicating whether the first unmatched child node matches the model.
+ */
 export function recursiveBranch(model, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNodes, specs, options, depth) {

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

@@ -1,8 +1,37 @@
 import type { ChildNode, Options, Result, Specs } from './types.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 declare const transparentMode: Map<ChildNode, true>;
+/**
+ * Represents a possible resolution of transparent content model nodes,
+ * containing the flattened list of child nodes to validate and any
+ * errors detected during transparent model resolution.
+ */
 type TransparentNode = {
     nodes: ChildNode[];
     errors: Result[];
 };
+/**
+ * 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. Uses `branchesToPatterns` to handle branching when multiple resolutions are possible.
+ *
+ * @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.
+ */
 export declare function representTransparentNodes(childNodes: readonly ChildNode[], specs: Specs, options: Options): TransparentNode[];
 export {};

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

@@ -2,7 +2,31 @@ 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();
+/**
+ * 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. Uses `branchesToPatterns` to handle branching when multiple resolutions are possible.
+ *
+ * @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.
+ */
 export function representTransparentNodes(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNodes, specs, options) {

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,19 +28,78 @@ 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>;
+    model: ReadonlyDeep<Model | PermittedContentPattern[]>;
     min: number;
     max: number;
     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;