@markuplint/rules 4.11.1 → 4.12.0

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

@@ -2,7 +2,16 @@ import { createRule, getAttrSpecs, ariaSpecs } from '@markuplint/ml-core';
 import { ARIA_RECOMMENDED_VERSION } from '@markuplint/ml-spec';
 import { decodeEntities, decodeHref } from '@markuplint/shared';
 import meta from './meta.js';
+/** CSS selector matching hyperlink elements that have an `href` attribute. */
 const HYPERLINK_SELECTOR = 'a[href], area[href]';
+/**
+ * Rule that validates all ID references in attributes point to existing elements.
+ *
+ * Checks DOMID and DOMID-list attributes (e.g., `for`, `aria-labelledby`),
+ * ARIA ID reference properties, and fragment identifiers in hyperlinks (`href="#id"`).
+ * Reports any reference to an ID that does not exist in the document. Skips
+ * validation when dynamic IDs or preprocessor blocks are detected.
+ */
 export default createRule({
     meta: meta,
     defaultOptions: {

package/lib/no-refer-to-non-existent-id/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-refer-to-non-existent-id` rule, categorized as accessibility. */
 declare const _default: {
     readonly category: "a11y";
 };

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

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-refer-to-non-existent-id` rule, categorized as accessibility. */
 export default {
     category: 'a11y',
 };

package/lib/no-use-event-handler-attr/index.d.ts

@@ -1,5 +1,15 @@
+/** Configuration options for the `no-use-event-handler-attr` rule. */
 type Options = {
+    /** Attribute name pattern(s) to exclude from the check. */
     ignore?: string | string[];
 };
+/**
+ * Rule that disallows inline event handler attributes (e.g., `onclick`,
+ * `onchange`).
+ *
+ * Reports any attribute on an HTML element whose name starts with `on`,
+ * indicating an inline event handler. An `ignore` option allows specific
+ * attribute names or patterns to be excluded from the check.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
 export default _default;

package/lib/no-use-event-handler-attr/index.js

@@ -1,6 +1,14 @@
 import { createRule } from '@markuplint/ml-core';
 import { match } from '../helpers.js';
 import meta from './meta.js';
+/**
+ * Rule that disallows inline event handler attributes (e.g., `onclick`,
+ * `onchange`).
+ *
+ * Reports any attribute on an HTML element whose name starts with `on`,
+ * indicating an inline event handler. An `ignore` option allows specific
+ * attribute names or patterns to be excluded from the check.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-use-event-handler-attr/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-use-event-handler-attr`: categorized as a maintainability rule. */
 declare const _default: {
     readonly category: "maintainability";
 };

package/lib/no-use-event-handler-attr/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-use-event-handler-attr`: categorized as a maintainability rule. */
 export default {
     category: 'maintainability',
 };

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

@@ -1,4 +1,21 @@
 import type { ChildNode, Options, Result, Specs } from './types.js';
 import type { PermittedContentChoice } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Evaluates a choice (alternation) pattern against a list of child nodes.
+ * Tries each branch of the choice in order and returns the first successful match.
+ * If no branch fully matches, selects the "barely matched" result that consumed
+ * the most nodes, preferring `UNEXPECTED_EXTRA_NODE` results (which indicate
+ * partial progress) over missing-node results.
+ *
+ * This implements the alternation (`|`) semantics found in content model definitions,
+ * e.g., "either flow content or phrasing content".
+ *
+ * @param pattern - The choice pattern containing multiple alternative content model branches.
+ * @param childNodes - The child nodes to validate against the choice branches.
+ * @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 result from the best-matching branch, or the branch that came closest to matching.
+ */
 export declare function choice(pattern: ReadonlyDeep<PermittedContentChoice>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): Result;

package/lib/permitted-contents/choice.js

@@ -1,7 +1,28 @@
 import { bgBlue, bgGreen, cmLog } from './debug.js';
 import { order } from './order.js';
 import { Collection, modelLog } from './utils.js';
+/**
+ * WeakMap that tracks which choice branch index produced each result,
+ * used for debug logging to identify the best-matching branch.
+ */
 const indexes = new WeakMap();
+/**
+ * Evaluates a choice (alternation) pattern against a list of child nodes.
+ * Tries each branch of the choice in order and returns the first successful match.
+ * If no branch fully matches, selects the "barely matched" result that consumed
+ * the most nodes, preferring `UNEXPECTED_EXTRA_NODE` results (which indicate
+ * partial progress) over missing-node results.
+ *
+ * This implements the alternation (`|`) semantics found in content model definitions,
+ * e.g., "either flow content or phrasing content".
+ *
+ * @param pattern - The choice pattern containing multiple alternative content model branches.
+ * @param childNodes - The child nodes to validate against the choice branches.
+ * @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 result from the best-matching branch, or the branch that came closest to matching.
+ */
 export function choice(pattern, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 childNodes, specs, options, depth) {
@@ -64,6 +85,15 @@ childNodes, specs, options, depth) {
         hint: barelyMatchedResult.hint,
     };
 }
+/**
+ * Formats a debug log string for a choice pattern, highlighting the selected
+ * branch index with a color (green for a full match, blue for a barely-matched fallback).
+ *
+ * @param choice - The array of choice branches from the pattern.
+ * @param index - The index of the selected branch.
+ * @param barely - Whether this is a barely-matched fallback (uses blue) or a full match (uses green).
+ * @returns A formatted string showing all branches with the selected one highlighted.
+ */
 function choiceLogString(choice, index, barely = false) {
     const colorFn = barely ? bgBlue : bgGreen;
     return choice

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

@@ -2,13 +2,17 @@ import type { ChildNode, Options, Result, Specs } from './types.js';
 import type { PermittedContentPattern } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
- * Check content condition
+ * Dispatches a single content model pattern to the appropriate handler based on its type.
+ * Acts as a routing layer in the content model validation pipeline:
+ * - Choice patterns (alternation) are delegated to `choice`.
+ * - Transparent patterns are delegated to `transparent`.
+ * - All other quantified patterns (require, optional, oneOrMore, zeroOrMore) are delegated to `countPattern`.
  *
- * @param pattern
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * @param pattern - A single content model pattern to evaluate.
+ * @param childNodes - The child nodes to validate against the pattern.
+ * @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 result indicating whether the child nodes match the pattern.
  */
 export declare function complexBranch(pattern: ReadonlyDeep<PermittedContentPattern>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): Result;

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

@@ -3,14 +3,18 @@ import { countPattern } from './count-pattern.js';
 import { transparent } from './transparent.js';
 import { isChoice, isTransparent } from './utils.js';
 /**
- * Check content condition
+ * Dispatches a single content model pattern to the appropriate handler based on its type.
+ * Acts as a routing layer in the content model validation pipeline:
+ * - Choice patterns (alternation) are delegated to `choice`.
+ * - Transparent patterns are delegated to `transparent`.
+ * - All other quantified patterns (require, optional, oneOrMore, zeroOrMore) are delegated to `countPattern`.
  *
- * @param pattern
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * @param pattern - A single content model pattern to evaluate.
+ * @param childNodes - The child nodes to validate against the pattern.
+ * @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 result indicating whether the child nodes match the pattern.
  */
 export function complexBranch(pattern, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

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

@@ -1,2 +1,13 @@
 import type { ContentModelResult, Element, Options, TagRule } from './types.js';
+/**
+ * Top-level entry point for content model validation of a single element.
+ * Resolves the element's content model from the spec (possibly augmented
+ * by user-defined tag rules), then delegates to `start` to validate
+ * the element's child nodes against that model.
+ *
+ * @param el - The element whose children are to be validated against its content model.
+ * @param rules - User-defined tag rules that can override or extend built-in content models.
+ * @param options - Validation behavior options (e.g., whether to ignore mutable children).
+ * @returns An array of content model results, one per child node issue found (empty if all valid).
+ */
 export declare function contentModel(el: Element, rules: readonly TagRule[], options: Options): ContentModelResult[];

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

@@ -1,5 +1,16 @@
 import { getContentModel } from '@markuplint/ml-spec';
 import { start } from './start.js';
+/**
+ * Top-level entry point for content model validation of a single element.
+ * Resolves the element's content model from the spec (possibly augmented
+ * by user-defined tag rules), then delegates to `start` to validate
+ * the element's child nodes against that model.
+ *
+ * @param el - The element whose children are to be validated against its content model.
+ * @param rules - User-defined tag rules that can override or extend built-in content models.
+ * @param options - Validation behavior options (e.g., whether to ignore mutable children).
+ * @returns An array of content model results, one per child node issue found (empty if all valid).
+ */
 export function contentModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, rules, options) {
@@ -17,6 +28,15 @@ el, rules, options) {
     const result = start(model, el, specs, options);
     return result;
 }
+/**
+ * Builds the content model and merged specs for a given element.
+ * Combines the element's document-level specs with any user-defined
+ * tag rules, then looks up the content model for the element.
+ *
+ * @param el - The element to look up the content model for.
+ * @param rules - User-defined tag rules to merge into the spec.
+ * @returns An object containing the resolved content model and merged specs.
+ */
 function createModel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, rules) {
@@ -27,7 +47,19 @@ el, rules) {
         specs,
     };
 }
+/**
+ * Cache for merged specs keyed by the JSON-serialized tag rules.
+ * Avoids re-merging the same set of user-defined tag rules on every element check.
+ */
 const caches = new Map();
+/**
+ * Returns a Specs object that merges the base ML spec with user-defined
+ * tag rules. Results are cached by the serialized rules to avoid redundant merging.
+ *
+ * @param specs - The base ML spec from the document.
+ * @param rules - User-defined tag rules to merge.
+ * @returns The merged Specs, either from cache or freshly computed.
+ */
 function cachedSpecs(specs, rules) {
     if (rules.length === 0) {
         return specs;

package/lib/permitted-contents/count-pattern.d.ts

@@ -2,13 +2,19 @@ import type { ChildNode, Options, Result, Specs } from './types.js';
 import type { PermittedContentOneOrMore, PermittedContentOptional, PermittedContentRequire, PermittedContentZeroOrMore } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
 /**
- * Check count
+ * Validates a quantified content model pattern (require, optional, oneOrMore, or zeroOrMore)
+ * against a list of child nodes. Repeatedly applies the inner pattern via `recursiveBranch`
+ * until the minimum count is satisfied and no more nodes match, or until the maximum count
+ * is exceeded.
  *
- * @param pattern
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * Implements the repetition/quantifier semantics of content models (e.g., "one or more
+ * flow content elements", "optionally a `<caption>`", "exactly one `<tbody>`").
+ *
+ * @param pattern - A quantified content model pattern (require, optional, oneOrMore, or zeroOrMore).
+ * @param childNodes - The child nodes to validate against the repeated pattern.
+ * @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 result indicating whether the required count of matches was achieved.
  */
 export declare function countPattern(pattern: ReadonlyDeep<PermittedContentOneOrMore> | ReadonlyDeep<PermittedContentOptional> | ReadonlyDeep<PermittedContentRequire> | ReadonlyDeep<PermittedContentZeroOrMore>, childNodes: readonly ChildNode[], specs: Specs, options: Options, depth: number): Result;

package/lib/permitted-contents/count-pattern.js

@@ -3,14 +3,20 @@ import { recursiveBranch } from './recursive-branch.js';
 import { Collection, mergeHints, modelLog, normalizeModel } from './utils.js';
 const cLog = cmLog.extend('countCompereResult');
 /**
- * Check count
+ * Validates a quantified content model pattern (require, optional, oneOrMore, or zeroOrMore)
+ * against a list of child nodes. Repeatedly applies the inner pattern via `recursiveBranch`
+ * until the minimum count is satisfied and no more nodes match, or until the maximum count
+ * is exceeded.
  *
- * @param pattern
- * @param childNodes
- * @param specs
- * @param options
- * @param depth
- * @returns
+ * Implements the repetition/quantifier semantics of content models (e.g., "one or more
+ * flow content elements", "optionally a `<caption>`", "exactly one `<tbody>`").
+ *
+ * @param pattern - A quantified content model pattern (require, optional, oneOrMore, or zeroOrMore).
+ * @param childNodes - The child nodes to validate against the repeated pattern.
+ * @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 result indicating whether the required count of matches was achieved.
  */
 export function countPattern(pattern, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -139,6 +145,16 @@ childNodes, specs, options, depth) {
         return compereResult(matchedResult, barelyResult);
     }
 }
+/**
+ * Compares two results and returns the one that represents the best diagnostic outcome.
+ * When the primary result is a match or an unexpected-extra-node, it is preferred.
+ * Otherwise, the result with more barely-matched elements (closer to success) is chosen
+ * to provide the most helpful error message.
+ *
+ * @param a - The primary (current iteration) result.
+ * @param b - The barely-matched result from a previous successful partial match, or null.
+ * @returns The result that should be reported to the user.
+ */
 function compereResult(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 a, 

package/lib/permitted-contents/debug.browser.d.ts

@@ -1,29 +1,41 @@
 import type { Log } from '../debug.js';
+/**
+ * Debug logger scoped to the content-model validation module (browser build).
+ * Extends the parent rule logger with a `content-model` namespace.
+ * In the browser environment, color helpers are no-op stubs.
+ */
 export declare const cmLog: Log;
+/** No-op color stub for browser environments: green background. */
 export declare const bgGreen: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: green foreground. */
 export declare const green: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: red background. */
 export declare const bgRed: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: blue background. */
 export declare const bgBlue: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: blue foreground. */
 export declare const blue: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: magenta background. */
 export declare const bgMagenta: {
     (): void;
     bold(): void;
 };
+/** No-op color stub for browser environments: cyan foreground. */
 export declare const cyan: {
     (): void;
     bold(): void;

package/lib/permitted-contents/debug.browser.js

@@ -1,11 +1,23 @@
 import { log } from '../debug.js';
+/**
+ * Debug logger scoped to the content-model validation module (browser build).
+ * Extends the parent rule logger with a `content-model` namespace.
+ * In the browser environment, color helpers are no-op stubs.
+ */
 export const cmLog = log.extend('content-model');
 const fn = () => { };
 fn.bold = () => { };
+/** No-op color stub for browser environments: green background. */
 export const bgGreen = fn;
+/** No-op color stub for browser environments: green foreground. */
 export const green = fn;
+/** No-op color stub for browser environments: red background. */
 export const bgRed = fn;
+/** No-op color stub for browser environments: blue background. */
 export const bgBlue = fn;
+/** No-op color stub for browser environments: blue foreground. */
 export const blue = fn;
+/** No-op color stub for browser environments: magenta background. */
 export const bgMagenta = fn;
+/** No-op color stub for browser environments: cyan foreground. */
 export const cyan = fn;

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

@@ -1,10 +1,22 @@
 import type { Log } from '../debug.js';
 import color from 'ansi-colors';
+/**
+ * Debug logger scoped to the content-model validation module.
+ * Extends the parent rule logger with a `content-model` namespace
+ * for structured debug output during content model evaluation.
+ */
 export declare const cmLog: Log;
+/** ANSI color helper: green background for highlighting locked-and-matched nodes in debug output. */
 export declare const bgGreen: color.StyleFunction;
+/** ANSI color helper: green foreground for highlighting matched nodes in debug output. */
 export declare const green: color.StyleFunction;
+/** ANSI color helper: red background for highlighting unexpected/extra nodes in debug output. */
 export declare const bgRed: color.StyleFunction;
+/** ANSI color helper: blue background for highlighting locked-and-matched transparent nodes in debug output. */
 export declare const bgBlue: color.StyleFunction;
+/** ANSI color helper: blue foreground for highlighting matched transparent nodes in debug output. */
 export declare const blue: color.StyleFunction;
+/** ANSI color helper: magenta background for highlighting unexpected transparent nodes in debug output. */
 export declare const bgMagenta: color.StyleFunction;
+/** ANSI color helper: cyan foreground for highlighting unmatched transparent nodes in debug output. */
 export declare const cyan: color.StyleFunction;

package/lib/permitted-contents/debug.js

@@ -1,10 +1,22 @@
 import color from 'ansi-colors';
 import { log } from '../debug.js';
+/**
+ * Debug logger scoped to the content-model validation module.
+ * Extends the parent rule logger with a `content-model` namespace
+ * for structured debug output during content model evaluation.
+ */
 export const cmLog = log.extend('content-model');
+/** ANSI color helper: green background for highlighting locked-and-matched nodes in debug output. */
 export const bgGreen = color.bgGreen;
+/** ANSI color helper: green foreground for highlighting matched nodes in debug output. */
 export const green = color.green;
+/** ANSI color helper: red background for highlighting unexpected/extra nodes in debug output. */
 export const bgRed = color.bgRed;
+/** ANSI color helper: blue background for highlighting locked-and-matched transparent nodes in debug output. */
 export const bgBlue = color.bgBlue;
+/** ANSI color helper: blue foreground for highlighting matched transparent nodes in debug output. */
 export const blue = color.blue;
+/** ANSI color helper: magenta background for highlighting unexpected transparent nodes in debug output. */
 export const bgMagenta = color.bgMagenta;
+/** ANSI color helper: cyan foreground for highlighting unmatched transparent nodes in debug output. */
 export const cyan = color.cyan;

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

@@ -1,3 +1,15 @@
 import type { Options, TagRule } from './types.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.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<TagRule[], Options>>;
 export default _default;

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;