@markuplint/rules 4.11.2 → 4.18.0

package/lib/permitted-contents/index.js

@@ -2,6 +2,18 @@ import { createRule } from '@markuplint/ml-core';
 import { contentModel } from './content-model.js';
 import meta from './meta.js';
 import { transparentMode } from './represent-transparent-nodes.js';
+/**
+ * The `permitted-contents` rule validates that each element's child nodes conform
+ * to the HTML content model specification. It is the most complex rule in markuplint,
+ * implementing a full content model validation engine that handles ordered sequences,
+ * quantified patterns (require, optional, oneOrMore, zeroOrMore), choice alternations,
+ * transparent content models, and conditional child node branches.
+ *
+ * For each element, it resolves the applicable content model (from the HTML spec or
+ * user-defined tag rules), evaluates the element's children against that model, and
+ * reports violations such as unexpected elements, missing required elements, or
+ * disallowed content through transparent models.
+ */
 export default createRule({
     meta: meta,
     defaultValue: [],
@@ -91,6 +103,15 @@ 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').
+ *
+ * @param scope - The child node to generate a name for.
+ * @param t - The translator function for localized message formatting.
+ * @returns A localized string describing the node.
+ */
 function name(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 scope, t) {

package/lib/permitted-contents/matches-selector.d.ts

@@ -1,3 +1,22 @@
 import type { ChildNode, Result, Specs } from './types.js';
+/**
+ * Extended result type for selector matching that includes additional
+ * intermediate states: a selector that did not match but allows empty content,
+ * a missing node, or unmatched selectors with partial matches.
+ */
 export type SelectorResult = Result<'UNMATCHED_SELECTOR_BUT_MAY_EMPTY' | 'MISSING_NODE' | 'UNMATCHED_SELECTORS'>;
+/**
+ * Tests whether a single child node matches a content model query selector.
+ * Handles special node types (text nodes, preprocessor blocks, custom elements)
+ * and delegates standard element matching to the CSS selector engine.
+ *
+ * The query string may reference content model categories (e.g., `#phrasing`)
+ * which are expanded to concrete tag selectors via `optCondition`.
+ *
+ * @param query - The content model query string (e.g., `"div"`, `"#phrasing"`, `":model(flow)"`).
+ * @param childNode - The child node to test, or undefined if no node is available.
+ * @param specs - The resolved spec data for category-to-tag-name expansion.
+ * @param depth - The current recursion depth, used for debug logging namespacing.
+ * @returns A selector result indicating match status with diagnostic hints.
+ */
 export declare function matchesSelector(query: string, childNode: ChildNode | undefined, specs: Specs, depth: number): SelectorResult;

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

@@ -1,6 +1,20 @@
 import { contentModelCategoryToTagNames } from '@markuplint/ml-spec';
 import { cmLog } from './debug.js';
 import { cleanObject, matches } from './utils.js';
+/**
+ * Tests whether a single child node matches a content model query selector.
+ * Handles special node types (text nodes, preprocessor blocks, custom elements)
+ * and delegates standard element matching to the CSS selector engine.
+ *
+ * The query string may reference content model categories (e.g., `#phrasing`)
+ * which are expanded to concrete tag selectors via `optCondition`.
+ *
+ * @param query - The content model query string (e.g., `"div"`, `"#phrasing"`, `":model(flow)"`).
+ * @param childNode - The child node to test, or undefined if no node is available.
+ * @param specs - The resolved spec data for category-to-tag-name expansion.
+ * @param depth - The current recursion depth, used for debug logging namespacing.
+ * @returns A selector result indicating match status with diagnostic hints.
+ */
 export function matchesSelector(query, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNode, specs, depth) {
@@ -127,6 +141,9 @@ childNode, specs, depth) {
         hint: {},
     };
 }
+/**
+ * Pre-computed conditions for well-known queries that do not depend on specs.
+ */
 const conditionWithoutSpecs = {
     '#custom': {
         selector: '#custom',
@@ -139,7 +156,23 @@ const conditionWithoutSpecs = {
         hasText: true,
     },
 };
+/**
+ * Cache of parsed conditions keyed by specs instance and query string.
+ * Prevents redundant category expansion for the same query across multiple elements.
+ */
 const optConditionSpecsBaseCaches = new Map();
+/**
+ * Parses a content model query string into a Condition object by expanding
+ * content model category references (e.g., `#phrasing`, `:model(flow)`) into
+ * concrete CSS `:is(...)` selectors. Also detects whether the query implicitly
+ * includes custom elements or text nodes.
+ *
+ * Results are cached per specs instance and query string.
+ *
+ * @param query - The raw content model query string to parse.
+ * @param specs - The spec data used to resolve category names to tag lists.
+ * @returns A readonly Condition with the resolved selector and flags.
+ */
 function optCondition(query, specs) {
     const condWithoutSpecs = conditionWithoutSpecs[query];
     if (condWithoutSpecs) {

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

@@ -1,3 +1,4 @@
+/** Rule metadata for the `permitted-contents` validation rule. */
 declare const _default: {
     readonly category: "validation";
 };

package/lib/permitted-contents/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `permitted-contents` validation rule. */
 export default {
     category: 'validation',
 };

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

@@ -2,13 +2,20 @@ import type { ChildNode, Options, Result, Specs } from './types.js';
 import type { PermittedContentPattern } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
- * Check ordered array
+ * Validates an ordered sequence of content model patterns against a list of child nodes.
+ * Each pattern in the `contents` array is matched in order against the remaining unmatched
+ * child nodes, consuming nodes as they match. This implements the sequential composition
+ * semantics of HTML content models (e.g., "a `<caption>` followed by zero or more `<colgroup>`s
+ * followed by a `<thead>`...").
  *
- * @param contents
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * Supports backtracking: when a pattern matches zero nodes (zeroMatch), the algorithm
+ * can backtrack to try the next pattern from the previous position if the current pattern fails.
+ *
+ * @param contents - An ordered array of content model patterns to match sequentially.
+ * @param childNodes - The child nodes to validate against the patterns.
+ * @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 pattern matching.
+ * @returns A result indicating overall match status and the matched/unmatched node partitioning.
  */
 export declare function order(contents: ReadonlyDeep<PermittedContentPattern[]>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): Result;

package/lib/permitted-contents/order.js

@@ -3,14 +3,21 @@ import { complexBranch } from './complex-branch.js';
 import { cmLog } from './debug.js';
 import { Collection, mergeHints, modelLog } from './utils.js';
 /**
- * Check ordered array
+ * Validates an ordered sequence of content model patterns against a list of child nodes.
+ * Each pattern in the `contents` array is matched in order against the remaining unmatched
+ * child nodes, consuming nodes as they match. This implements the sequential composition
+ * semantics of HTML content models (e.g., "a `<caption>` followed by zero or more `<colgroup>`s
+ * followed by a `<thead>`...").
  *
- * @param contents
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * Supports backtracking: when a pattern matches zero nodes (zeroMatch), the algorithm
+ * can backtrack to try the next pattern from the previous position if the current pattern fails.
+ *
+ * @param contents - An ordered array of content model patterns to match sequentially.
+ * @param childNodes - The child nodes to validate against the patterns.
+ * @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 pattern matching.
+ * @returns A result indicating overall match status and the matched/unmatched node partitioning.
  */
 export function order(contents, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

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;
 };