@markuplint/rules 4.11.2 → 4.18.0

package/lib/no-empty-palpable-content/index.d.ts

@@ -1,6 +1,19 @@
+/**
+ * Configuration options for the no-empty-palpable-content rule.
+ */
 type Options = {
+    /** Whether to extend checking to exposable elements beyond standard palpable content. */
     extendsExposableElements?: boolean;
+    /** Whether to ignore elements marked with `aria-busy="true"`. */
     ignoreIfAriaBusy?: boolean;
 };
+/**
+ * Rule that warns when palpable content elements are empty.
+ *
+ * Palpable content elements are expected to have visible or meaningful content.
+ * This rule reports elements that contain only whitespace text nodes, while
+ * excluding elements that are naturally empty (e.g., `<textarea>`, `<video>`)
+ * or have a nothing content model.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
 export default _default;

package/lib/no-empty-palpable-content/index.js

@@ -1,6 +1,10 @@
 import { createRule } from '@markuplint/ml-core';
 import { isNothingContentModel, isPalpableElement } from '@markuplint/ml-spec';
 import meta from './meta.js';
+/**
+ * Elements that are allowed to be empty because they are filled by user
+ * interaction or are inherently palpable by themselves.
+ */
 const allowedElements = new Set([
     // These elements are possibly empty because it to be filled by user interaction.
     'textarea',
@@ -11,6 +15,14 @@ const allowedElements = new Set([
     'video',
     'img',
 ]);
+/**
+ * Rule that warns when palpable content elements are empty.
+ *
+ * Palpable content elements are expected to have visible or meaningful content.
+ * This rule reports elements that contain only whitespace text nodes, while
+ * excluding elements that are naturally empty (e.g., `<textarea>`, `<video>`)
+ * or have a nothing content model.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-empty-palpable-content/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-empty-palpable-content` rule, categorized as validation. */
 declare const _default: {
     readonly category: "validation";
 };

package/lib/no-empty-palpable-content/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `no-empty-palpable-content` rule, categorized as validation. */
 export default {
     category: 'validation',
 };

package/lib/no-hard-code-id/index.d.ts

@@ -1,2 +1,10 @@
+/**
+ * Rule that disallows hard-coded `id` attribute values in document fragments.
+ *
+ * Only active for fragment documents (e.g., component templates). Reports
+ * any `id` attribute whose value is a static string rather than a dynamic
+ * or code-generated value, encouraging dynamic ID generation to avoid
+ * collisions when fragments are reused.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/no-hard-code-id/index.js

@@ -1,5 +1,13 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that disallows hard-coded `id` attribute values in document fragments.
+ *
+ * Only active for fragment documents (e.g., component templates). Reports
+ * any `id` attribute whose value is a static string rather than a dynamic
+ * or code-generated value, encouraging dynamic ID generation to avoid
+ * collisions when fragments are reused.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/no-hard-code-id/meta.d.ts

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

package/lib/no-hard-code-id/meta.js

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

package/lib/no-orphaned-end-tag/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Rule that detects orphaned end tags with no matching start tag.
+ *
+ * Scans text nodes for content that looks like a closing tag (starts with
+ * `</`) which indicates a stray end tag that the parser could not match
+ * to an opening element.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, null>>;
 export default _default;

package/lib/no-orphaned-end-tag/index.js

@@ -1,5 +1,12 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that detects orphaned end tags with no matching start tag.
+ *
+ * Scans text nodes for content that looks like a closing tag (starts with
+ * `</`) which indicates a stray end tag that the parser could not match
+ * to an opening element.
+ */
 export default createRule({
     meta,
     async verify({ document, report, t }) {

package/lib/no-orphaned-end-tag/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-orphaned-end-tag`: categorized as a validation rule. */
 declare const _default: {
     readonly category: "validation";
 };

package/lib/no-orphaned-end-tag/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `no-orphaned-end-tag`: categorized as a validation rule. */
 export default {
     category: 'validation',
 };

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

@@ -1,4 +1,12 @@
 import type { ARIAVersion } from '@markuplint/ml-spec';
+/**
+ * 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.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, {
     ariaVersion: ARIAVersion;
     fragmentRefersNameAttr: boolean;

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;