@markuplint/rules 4.11.2 → 4.12.0

package/CHANGELOG.md

@@ -3,13 +3,16 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.11.2](https://github.com/markuplint/markuplint/compare/@markuplint/rules@4.11.1...@markuplint/rules@4.11.2) (2025-11-05)
-
-**Note:** Version bump only for package @markuplint/rules
+# [4.12.0](https://github.com/markuplint/markuplint/compare/@markuplint/rules@4.11.2...@markuplint/rules@4.12.0) (2026-02-10)
 
+### Features
 
+- **rules:** add ignoreOmittedElements option to required-element ([0cc879c](https://github.com/markuplint/markuplint/commit/0cc879ca175491da7eda4d6f4d0638b74fe528e5)), closes [#2066](https://github.com/markuplint/markuplint/issues/2066)
+- **rules:** support Invoker Commands API in neighbor-popovers rule ([963853f](https://github.com/markuplint/markuplint/commit/963853f9f3701ab552d7d03fe5712a671c50d444)), closes [#3065](https://github.com/markuplint/markuplint/issues/3065)
 
+## [4.11.2](https://github.com/markuplint/markuplint/compare/@markuplint/rules@4.11.1...@markuplint/rules@4.11.2) (2025-11-05)
 
+**Note:** Version bump only for package @markuplint/rules
 
 ## [4.11.1](https://github.com/markuplint/markuplint/compare/@markuplint/rules@4.11.0...@markuplint/rules@4.11.1) (2025-08-24)
 

package/SKILL.md

@@ -0,0 +1,76 @@
+---
+description: Perform maintenance tasks for @markuplint/rules
+---
+
+# rules-maintenance
+
+Maintain rule test suites, especially when `@markuplint/html-spec` changes.
+
+## Input
+
+`$ARGUMENTS` specifies the task:
+
+| Task                              | Description                           |
+| --------------------------------- | ------------------------------------- |
+| `add-spec-tests <rule> <element>` | Add tests after a spec change         |
+| `update-test-expectations`        | Fix tests broken by spec data changes |
+
+## Task: add-spec-tests
+
+### Which test file?
+
+| Spec change                         | Test file                              |
+| ----------------------------------- | -------------------------------------- |
+| ARIA (implicitRole, permittedRoles) | `src/wai-aria/index.spec.ts`           |
+| Attributes (new/changed/enum)       | `src/invalid-attr/index.spec.ts`       |
+| Content model                       | `src/permitted-contents/index.spec.ts` |
+
+### Test Pattern
+
+```typescript
+import { mlRuleTest } from 'markuplint';
+import rule from './index.js';
+
+// Valid case — no violations
+const { violations } = await mlRuleTest(rule, '<img src="x.png" alt="desc" role="math">');
+expect(violations).toStrictEqual([]);
+
+// Invalid case — exact violation object
+const { violations } = await mlRuleTest(rule, '<img src="x.png" alt="desc" role="navigation">');
+expect(violations).toStrictEqual([
+  {
+    severity: 'error',
+    line: 1,
+    col: 38,
+    message: 'Cannot overwrite the "navigation" role to the "img" element according to ARIA in HTML specification',
+    raw: 'navigation',
+  },
+]);
+
+// ARIA version test
+const { violations } = await mlRuleTest(rule, '<button role="separator" ...>', {
+  rule: { options: { version: '1.1' } },
+});
+```
+
+### Conventions
+
+- `toStrictEqual` with exact `{ severity, line, col, message, raw }` — **never** loose assertions
+- Always include both valid and invalid cases
+- Some roles need ARIA attributes in HTML: `separator` → `aria-valuenow`, `meter` → `aria-valuenow`
+
+## Task: update-test-expectations
+
+When `html-spec` data changes break existing tests:
+
+1. Run `yarn test` to find failures
+2. Verify the new behavior is correct (not a regression)
+3. Update expected violation objects (message strings, etc.)
+4. Common cause: adding enum values changes error message strings
+
+## Rules
+
+1. **Always run `yarn test` (full suite)**, not just the rules package
+2. **Use `toStrictEqual` with exact objects** — no loose assertions
+3. **Check `ml-spec` algorithm tests** when changing ARIA mappings —
+   `ml-spec/src/algorithm/aria/get-permitted-roles-spec.spec.ts` has hardcoded role arrays

package/lib/attr-check.d.ts

@@ -1,25 +1,61 @@
 import type { Translator } from '@markuplint/i18n';
 import type { Attribute as AttrSpec, AttributeType } from '@markuplint/ml-spec';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Discriminated union tag representing the kind of attribute invalidity.
+ */
 type InvalidTYpe = 'non-existent' | 'invalid-value' | 'disallowed-attr';
+/**
+ * Describes a single attribute validation failure, including the kind
+ * of invalidity, a human-readable message, and an optional source location.
+ *
+ * @template T - The specific invalidity tag (defaults to any `InvalidTYpe`)
+ */
 type Invalid<T extends InvalidTYpe = InvalidTYpe> = {
     invalidType: T;
     message: string;
     loc?: Loc;
 };
+/**
+ * Source location information pointing to the invalid portion of an attribute value.
+ */
 type Loc = {
     raw: string;
     line: number;
     col: number;
 };
 /**
- * Use in rules `invalid-attr` and `wai-aria`
+ * Validates an attribute against its specification. Used by the `invalid-attr`
+ * and `wai-aria` rules.
+ *
+ * Performs the following checks in order:
+ * 1. Skips `data-*`, `aria-*`/`role`, and `adapt-*` attributes (unless `isCustomRule` is `true`)
+ * 2. Verifies the attribute exists in the spec
+ * 3. Checks case-sensitive name matching
+ * 4. Checks whether the attribute is marked as `noUse` (disallowed)
+ * 5. Validates the attribute value against all declared types
  *
- * @param name
- * @param value
- * @param isCustomRule
- * @param spec
+ * @param t - The i18n translator for generating localized error messages
+ * @param name - The attribute name to check
+ * @param value - The attribute value to validate
+ * @param isCustomRule - When `true`, skips the built-in bypass for `data-*`, `aria-*`, and `adapt-*` attributes
+ * @param spec - The attribute specification to validate against; if absent, the attribute is considered non-existent
+ * @returns `false` if the attribute is valid, a single `Invalid` object for existence/disallowed errors,
+ *   or an array of `Invalid<'invalid-value'>` objects for value validation failures
  */
 export declare function attrCheck(t: Translator, name: string, value: string, isCustomRule: boolean, spec?: AttrSpec): Invalid | Invalid<'invalid-value'>[] | false;
+/**
+ * Validates an attribute value against a single attribute type definition.
+ * Returns `false` if the value is valid, or a tuple of `[message, location]`
+ * describing the mismatch.
+ *
+ * Boolean attributes are always considered valid (their mere presence is sufficient).
+ *
+ * @param t - The i18n translator for generating localized error messages
+ * @param name - The attribute name (used in error messages)
+ * @param value - The attribute value to validate
+ * @param type - The attribute type definition to validate against
+ * @returns `false` if the value is valid, or a `[message, location]` tuple on failure
+ */
 export declare function valueCheck(t: Translator, name: string, value: string, type: ReadonlyDeep<AttributeType>): [string, Loc] | false;
 export {};

package/lib/attr-check.js

@@ -3,12 +3,23 @@ import { check } from '@markuplint/types';
 import { createMessageValueExpected } from './create-message.js';
 import { log } from './debug.js';
 /**
- * Use in rules `invalid-attr` and `wai-aria`
+ * Validates an attribute against its specification. Used by the `invalid-attr`
+ * and `wai-aria` rules.
  *
- * @param name
- * @param value
- * @param isCustomRule
- * @param spec
+ * Performs the following checks in order:
+ * 1. Skips `data-*`, `aria-*`/`role`, and `adapt-*` attributes (unless `isCustomRule` is `true`)
+ * 2. Verifies the attribute exists in the spec
+ * 3. Checks case-sensitive name matching
+ * 4. Checks whether the attribute is marked as `noUse` (disallowed)
+ * 5. Validates the attribute value against all declared types
+ *
+ * @param t - The i18n translator for generating localized error messages
+ * @param name - The attribute name to check
+ * @param value - The attribute value to validate
+ * @param isCustomRule - When `true`, skips the built-in bypass for `data-*`, `aria-*`, and `adapt-*` attributes
+ * @param spec - The attribute specification to validate against; if absent, the attribute is considered non-existent
+ * @returns `false` if the attribute is valid, a single `Invalid` object for existence/disallowed errors,
+ *   or an array of `Invalid<'invalid-value'>` objects for value validation failures
  */
 export function attrCheck(t, name, value, isCustomRule, spec) {
     if (!isCustomRule) {
@@ -68,6 +79,19 @@ export function attrCheck(t, name, value, isCustomRule, spec) {
     }
     return [...invalidMap.values()];
 }
+/**
+ * Validates an attribute value against a single attribute type definition.
+ * Returns `false` if the value is valid, or a tuple of `[message, location]`
+ * describing the mismatch.
+ *
+ * Boolean attributes are always considered valid (their mere presence is sufficient).
+ *
+ * @param t - The i18n translator for generating localized error messages
+ * @param name - The attribute name (used in error messages)
+ * @param value - The attribute value to validate
+ * @param type - The attribute type definition to validate against
+ * @returns `false` if the value is valid, or a `[message, location]` tuple on failure
+ */
 export function valueCheck(t, name, value, type) {
     if (type === 'Boolean') {
         // Valid because an attribute is exist

package/lib/attr-duplication/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Rule that checks for duplicate attributes on the same element.
+ *
+ * Walks all elements and reports when two or more attributes share the same
+ * name (case-insensitive for HTML elements). Attributes marked as duplicatable
+ * (e.g., template-engine directives) are excluded from this check.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/attr-duplication/index.js

@@ -1,5 +1,12 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that checks for duplicate attributes on the same element.
+ *
+ * Walks all elements and reports when two or more attributes share the same
+ * name (case-insensitive for HTML elements). Attributes marked as duplicatable
+ * (e.g., template-engine directives) are excluded from this check.
+ */
 export default createRule({
     meta: meta,
     async verify({ document, report, t }) {

package/lib/attr-duplication/meta.d.ts

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

package/lib/attr-duplication/meta.js

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

package/lib/attr-value-quotes/index.d.ts

@@ -1,7 +1,17 @@
+/** The accepted quote style: double or single. */
 export type Type = 'double' | 'single';
+/** A literal quotation mark character. */
 export type Quote = '"' | "'";
+/** Maps each quote style name to its corresponding character. */
 export type QuoteMap = {
     [P in Type]: Quote;
 };
+/**
+ * Rule that enforces consistent quotation marks around attribute values.
+ *
+ * Verifies that all attribute values use the configured quote style (double
+ * or single). Attributes without values, dynamic values, and directives are
+ * skipped. Includes an auto-fix that replaces mismatched quotes.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<Type, undefined>>;
 export default _default;

package/lib/attr-value-quotes/index.js

@@ -1,9 +1,19 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Mapping from quote type names to their literal characters.
+ */
 const quoteList = {
     double: '"',
     single: "'",
 };
+/**
+ * Rule that enforces consistent quotation marks around attribute values.
+ *
+ * Verifies that all attribute values use the configured quote style (double
+ * or single). Attributes without values, dynamic values, and directives are
+ * skipped. Includes an auto-fix that replaces mismatched quotes.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/attr-value-quotes/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `attr-value-quotes`: categorized as a style rule. */
 declare const _default: {
     readonly category: "style";
 };

package/lib/attr-value-quotes/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `attr-value-quotes`: categorized as a style rule. */
 export default {
     category: 'style',
 };

package/lib/case-sensitive-attr-name/index.d.ts

@@ -1,3 +1,12 @@
+/** The enforced letter case for attribute names. */
 export type Value = 'lower' | 'upper';
+/**
+ * Rule that enforces consistent letter case for HTML attribute names.
+ *
+ * Reports attribute names that do not match the configured case (lower or upper)
+ * on HTML elements. Foreign elements and case-sensitive attributes (per spec)
+ * are excluded. Includes an auto-fix that converts attribute names to the
+ * configured case.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<Value, undefined>>;
 export default _default;

package/lib/case-sensitive-attr-name/index.js

@@ -1,5 +1,13 @@
 import { createRule, getAttrSpecs } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that enforces consistent letter case for HTML attribute names.
+ *
+ * Reports attribute names that do not match the configured case (lower or upper)
+ * on HTML elements. Foreign elements and case-sensitive attributes (per spec)
+ * are excluded. Includes an auto-fix that converts attribute names to the
+ * configured case.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/case-sensitive-attr-name/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `case-sensitive-attr-name`: categorized as a style rule. */
 declare const _default: {
     readonly category: "style";
 };

package/lib/case-sensitive-attr-name/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `case-sensitive-attr-name`: categorized as a style rule. */
 export default {
     category: 'style',
 };

package/lib/case-sensitive-tag-name/index.d.ts

@@ -1,3 +1,12 @@
+/** The enforced letter case for tag names. */
 export type Value = 'lower' | 'upper';
+/**
+ * Rule that enforces consistent letter case for HTML tag names.
+ *
+ * Reports opening and closing tag names that do not match the configured
+ * case (lower or upper) on HTML elements. Skipped when the document is
+ * tag-name-case-sensitive or for foreign elements. Includes an auto-fix
+ * that converts tag names to the configured case.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<Value, undefined>>;
 export default _default;

package/lib/case-sensitive-tag-name/index.js

@@ -1,5 +1,13 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that enforces consistent letter case for HTML tag names.
+ *
+ * Reports opening and closing tag names that do not match the configured
+ * case (lower or upper) on HTML elements. Skipped when the document is
+ * tag-name-case-sensitive or for foreign elements. Includes an auto-fix
+ * that converts tag names to the configured case.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/case-sensitive-tag-name/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `case-sensitive-tag-name`: categorized as a style rule. */
 declare const _default: {
     readonly category: "style";
 };

package/lib/case-sensitive-tag-name/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `case-sensitive-tag-name`: categorized as a style rule. */
 export default {
     category: 'style',
 };

package/lib/character-reference/index.d.ts

@@ -1,3 +1,11 @@
 import type { RuleConfigValue } from '@markuplint/ml-config';
+/**
+ * Rule that checks whether special characters are properly escaped as
+ * character references.
+ *
+ * Scans text nodes and attribute values for the characters `"`, `&`, `<`,
+ * and `>` that are not already part of a valid character reference. Text
+ * inside `<script>` and `<style>` elements is excluded.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<RuleConfigValue, undefined>>;
 export default _default;

package/lib/character-reference/index.js

@@ -1,7 +1,23 @@
 import { createRule, getLocationFromChars } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Characters that must be escaped using character references in HTML text
+ * and attribute values.
+ */
 const defaultChars = ['"', '&', '<', '>'];
+/**
+ * Parent elements whose text content is exempt from character reference checks
+ * because their content is not parsed as HTML.
+ */
 const ignoreParentElement = new Set(['script', 'style']);
+/**
+ * Rule that checks whether special characters are properly escaped as
+ * character references.
+ *
+ * Scans text nodes and attribute values for the characters `"`, `&`, `<`,
+ * and `>` that are not already part of a valid character reference. Text
+ * inside `<script>` and `<style>` elements is excluded.
+ */
 export default createRule({
     meta: meta,
     async verify({ document, report, t }) {

package/lib/character-reference/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `character-reference`: categorized as a style rule. */
 declare const _default: {
     readonly category: "style";
 };

package/lib/character-reference/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `character-reference`: categorized as a style rule. */
 export default {
     category: 'style',
 };

package/lib/class-naming/index.d.ts

@@ -1,3 +1,12 @@
+/** One or more regex or glob patterns that class names must match, or `null` to disable. */
 export type Value = string | string[] | null;
+/**
+ * Rule that validates class attribute values against configured naming patterns.
+ *
+ * Splits the `class` attribute into individual class names and checks each
+ * one against the provided string or regex patterns. Reports any class name
+ * that does not match at least one of the configured patterns. Dynamic
+ * values are excluded from the check.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<Value, undefined>>;
 export default _default;

package/lib/class-naming/index.js

@@ -2,6 +2,14 @@ import { createRule } from '@markuplint/ml-core';
 import { toNoEmptyStringArrayFromStringOrArray } from '@markuplint/shared';
 import { match } from '../helpers.js';
 import meta from './meta.js';
+/**
+ * Rule that validates class attribute values against configured naming patterns.
+ *
+ * Splits the `class` attribute into individual class names and checks each
+ * one against the provided string or regex patterns. Reports any class name
+ * that does not match at least one of the configured patterns. Dynamic
+ * values are excluded from the check.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

package/lib/class-naming/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for `class-naming`: categorized as a naming-convention rule. */
 declare const _default: {
     readonly category: "naming-convention";
 };

package/lib/class-naming/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for `class-naming`: categorized as a naming-convention rule. */
 export default {
     category: 'naming-convention',
 };

package/lib/create-message.d.ts

@@ -2,5 +2,32 @@ import type { Translator } from '@markuplint/i18n';
 import type { AttributeType } from '@markuplint/ml-spec';
 import type { UnmatchedResult } from '@markuplint/types';
 import type { ReadonlyDeep } from 'type-fest';
+/**
+ * Builds a human-readable error message explaining why an attribute value
+ * does not match its expected type. Handles both plain types and list types
+ * (space-separated or comma-separated).
+ *
+ * @param t - The i18n translator for generating localized messages
+ * @param baseTarget - A human-readable description of the attribute being validated
+ *   (e.g. `'the "href" attribute'`)
+ * @param type - The attribute type definition that the value was validated against
+ * @param matches - The result object from a failed type check, containing
+ *   details about the mismatch (reason, candidate, part name, etc.)
+ * @returns A localized error message describing the expected value
+ */
 export declare function createMessageValueExpected(t: Translator, baseTarget: string, type: ReadonlyDeep<AttributeType>, matches: UnmatchedResult): string;
+/**
+ * Assembles the detailed portion of a value-expected error message by
+ * inspecting the mismatch reason and composing reason, expectation,
+ * candidate suggestion, and fallback parts into a single string.
+ *
+ * This is an internal helper exposed for testing and advanced use.
+ * The double-underscore prefix indicates it is not part of the stable public API.
+ *
+ * @param t - The i18n translator for generating localized messages
+ * @param baseTarget - A human-readable description of the validation target
+ * @param expected - A description of the expected value(s), or `null` if unknown
+ * @param matches - Partial match result containing reason, candidate, and other details
+ * @returns A localized error message string
+ */
 export declare function __createMessageValueExpected(t: Translator, baseTarget: string, expected: string | null, matches: Pick<UnmatchedResult, 'partName' | 'reason' | 'raw' | 'candidate' | 'ref' | 'extra' | 'fallbackTo'>): string;

package/lib/create-message.js

@@ -1,4 +1,17 @@
 import { isList, isKeyword, isEnum, isNumber, isDirective } from '@markuplint/types';
+/**
+ * Builds a human-readable error message explaining why an attribute value
+ * does not match its expected type. Handles both plain types and list types
+ * (space-separated or comma-separated).
+ *
+ * @param t - The i18n translator for generating localized messages
+ * @param baseTarget - A human-readable description of the attribute being validated
+ *   (e.g. `'the "href" attribute'`)
+ * @param type - The attribute type definition that the value was validated against
+ * @param matches - The result object from a failed type check, containing
+ *   details about the mismatch (reason, candidate, part name, etc.)
+ * @returns A localized error message describing the expected value
+ */
 export function createMessageValueExpected(t, baseTarget, type, matches) {
     let target = baseTarget;
     let listDescriptionPart;
@@ -17,6 +30,20 @@ export function createMessageValueExpected(t, baseTarget, type, matches) {
         .join(t('. '));
     return message;
 }
+/**
+ * Assembles the detailed portion of a value-expected error message by
+ * inspecting the mismatch reason and composing reason, expectation,
+ * candidate suggestion, and fallback parts into a single string.
+ *
+ * This is an internal helper exposed for testing and advanced use.
+ * The double-underscore prefix indicates it is not part of the stable public API.
+ *
+ * @param t - The i18n translator for generating localized messages
+ * @param baseTarget - A human-readable description of the validation target
+ * @param expected - A description of the expected value(s), or `null` if unknown
+ * @param matches - Partial match result containing reason, candidate, and other details
+ * @returns A localized error message string
+ */
 export function __createMessageValueExpected(t, baseTarget, expected, matches) {
     let target = baseTarget;
     let reasonPart;
@@ -132,7 +159,7 @@ export function __createMessageValueExpected(t, baseTarget, expected, matches) {
                 switch (matches.reason.type) {
                     case 'out-of-range-length-digit': {
                         const { gte, lte } = matches.reason;
-                        let expectedDigits = null;
+                        let expectedDigits;
                         if (lte != null && gte === lte) {
                             expectedDigits = t('{0} digits', gte);
                         }
@@ -199,6 +226,17 @@ export function __createMessageValueExpected(t, baseTarget, expected, matches) {
     }
     return message;
 }
+/**
+ * Derives a human-readable description of the expected value from an attribute
+ * type definition and the unmatched result. Inspects keywords, enums, numbers,
+ * directives, and explicit `expects` entries from the match result.
+ *
+ * @param type - The attribute type (excluding list wrappers)
+ * @param matches - The unmatched result containing optional `expects` hints
+ * @param t - The i18n translator
+ * @returns A localized string describing the expected value(s), or `null` if
+ *   no expectation can be determined
+ */
 function createExpectedObject(type, matches, t) {
     const expectedObject = [];
     if (matches.expects && matches.expects.length > 0) {
@@ -227,6 +265,14 @@ function createExpectedObject(type, matches, t) {
             : (expectedObject[0] ?? null);
     return expects;
 }
+/**
+ * Converts a single `Expect` descriptor into a human-readable word or phrase.
+ *
+ * @param t - The i18n translator
+ * @param expect - The expectation descriptor from a type-check result
+ * @param type - The attribute type context for determining phrasing (e.g. CSS syntax)
+ * @returns A localized word or phrase describing the expected value
+ */
 function expectValueToWord(t, expect, type) {
     switch (expect.type) {
         case 'common': {
@@ -249,6 +295,15 @@ function expectValueToWord(t, expect, type) {
         }
     }
 }
+/**
+ * Builds a human-readable description of an expected numeric range
+ * from a `Number` type definition (e.g. "integer greater than or equal to 0").
+ *
+ * @param t - The i18n translator
+ * @param type - The number type definition containing range constraints
+ *   (`gt`, `gte`, `lt`, `lte`) and the numeric type label
+ * @returns A localized description of the expected numeric range
+ */
 function createExpectedNumber(t, type) {
     if (type.gt != null) {
         if (type.lt != null) {

package/lib/debug.d.ts

@@ -1,3 +1,12 @@
 import debug from 'debug';
+/**
+ * Type alias for the debug logger function provided by the `debug` package.
+ * Used throughout the rules package for conditional diagnostic logging.
+ */
 export type Log = debug.Debugger;
+/**
+ * Shared debug logger instance for the `@markuplint/rules` package.
+ * Enable by setting the `DEBUG` environment variable to include `ml-rules`
+ * (e.g. `DEBUG=ml-rules`).
+ */
 export declare const log: debug.Debugger;

package/lib/debug.js

@@ -1,2 +1,7 @@
 import debug from 'debug';
+/**
+ * Shared debug logger instance for the `@markuplint/rules` package.
+ * Enable by setting the `DEBUG` environment variable to include `ml-rules`
+ * (e.g. `DEBUG=ml-rules`).
+ */
 export const log = debug('ml-rules');

package/lib/deprecated-attr/index.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Rule that reports the use of deprecated or obsolete HTML attributes.
+ *
+ * Checks each attribute against the HTML spec and reports any that are
+ * marked as deprecated or obsolete.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/deprecated-attr/index.js

@@ -1,5 +1,11 @@
 import { createRule, getAttrSpecs } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that reports the use of deprecated or obsolete HTML attributes.
+ *
+ * Checks each attribute against the HTML spec and reports any that are
+ * marked as deprecated or obsolete.
+ */
 export default createRule({
     meta: meta,
     async verify({ document, report, t }) {