@markuplint/rules 4.11.2 → 5.0.0-alpha.0

package/CHANGELOG.md

@@ -3,13 +3,74 @@
 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)
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
 
-**Note:** Version bump only for package @markuplint/rules
+### Bug Fixes
 
+- **rules:** address review feedback for require-dialog-autofocus ([6fcadb2](https://github.com/markuplint/markuplint/commit/6fcadb2ab0e6a974e8ba6f644eff914a7840b8ef))
+- treat orphaned end tags as bogus instead of plain text ([#1575](https://github.com/markuplint/markuplint/issues/1575)) ([557199a](https://github.com/markuplint/markuplint/commit/557199a6960ab35573a544f9a33c00e98eb9967e))
 
+- feat(rules)!: simplify invalid-attr options and remove attrs ([3ced12d](https://github.com/markuplint/markuplint/commit/3ced12d200f12ba4c9e177c9aaca25e7e24a9151))
+- feat(rules)!: add no-unsupported-features rule for browser support checks ([8525a96](https://github.com/markuplint/markuplint/commit/8525a96fb04f634820362a9a73d6541284b53686))
+- feat(rules)!: change ignoreOmittedElements default to true ([5ec04a7](https://github.com/markuplint/markuplint/commit/5ec04a7d63cbf19846b42124c22653197f603a59)), closes [#3136](https://github.com/markuplint/markuplint/issues/3136)
+- refactor(rules)!: replace selfClosingSolidus with tagCloseChar ([f9cd9d8](https://github.com/markuplint/markuplint/commit/f9cd9d81bfb0ba49c2578eace7b04a9a1ebdd12a))
 
+### Features
+
+- **html-spec:** require href or imagesrcset on link element ([e6a2631](https://github.com/markuplint/markuplint/commit/e6a26318ed8e4be9ba4e81884eb0b879a816efb5)), closes [#717](https://github.com/markuplint/markuplint/issues/717)
+- **ml-spec,rules:** adopt ARIA 1.3 property names with 1.2 compat ([4f7e54d](https://github.com/markuplint/markuplint/commit/4f7e54d21593495d36e48fbe8ad27f8be85ab5ef))
+- **rules:** add correct-aspect-ratio rule ([4068582](https://github.com/markuplint/markuplint/commit/40685828da697dfa8565288438a5d027dd0fae45))
+- **rules:** add ignoreAttrs option to required-attr rule ([#690](https://github.com/markuplint/markuplint/issues/690)) ([fe4ce5e](https://github.com/markuplint/markuplint/commit/fe4ce5e283bc9e5284d209322dc0bbe3cbe07d55))
+- **rules:** add link-types rule for rel attribute validation ([95d22a5](https://github.com/markuplint/markuplint/commit/95d22a596c1f786c385b7e99c3b818434995f4b5))
+- **rules:** add redundant-accessible-name rule for detecting overridden accessible name sources ([63b89d4](https://github.com/markuplint/markuplint/commit/63b89d47bf5056f823d5b27cda4fda2b96419bb3))
+- **rules:** add require-dialog-autofocus rule ([2d8d650](https://github.com/markuplint/markuplint/commit/2d8d650f8bc82e706687d292b27c310f3552b418)), closes [#689](https://github.com/markuplint/markuplint/issues/689)
+- **rules:** add required context role check to wai-aria rule ([#970](https://github.com/markuplint/markuplint/issues/970)) ([1433a5a](https://github.com/markuplint/markuplint/commit/1433a5ae429aca4e7dc0a1a7f514a184eb423c03))
+- **rules:** add srcset-sizes-constraint rule ([#1051](https://github.com/markuplint/markuplint/issues/1051)) ([bcc624a](https://github.com/markuplint/markuplint/commit/bcc624a3c6535ef85ad155b05d7571198983277a))
+- **rules:** recognize DPub ARIA roles in wai-aria rule ([3dd32ff](https://github.com/markuplint/markuplint/commit/3dd32ffa7e5e706bad33bf9b9ff1785de8c8e630))
+- **rules:** suggest similar attribute names for typos in invalid-attr rule ([337c7c5](https://github.com/markuplint/markuplint/commit/337c7c56b792cf7bc72baa3a2528f0c93892d550)), closes [#1487](https://github.com/markuplint/markuplint/issues/1487)
+- **rules:** support ARIA 1.3 generic transparency in owned elements check ([c1d6991](https://github.com/markuplint/markuplint/commit/c1d6991cb197d511c5751bba183fde1208001590))
+- **rules:** support source elements inside picture in correct-aspect-ratio ([3cd3dc9](https://github.com/markuplint/markuplint/commit/3cd3dc9981a04f4ff5b78b97c28cc7852d31886e))
+- **rules:** use ruleCommonSettings.ariaVersion fallback in ARIA rules ([07ccd8a](https://github.com/markuplint/markuplint/commit/07ccd8acd8b9db11ccf473b419a3d01cc782e15c))
+
+### Performance Improvements
+
+- **rules:** fix exponential slowdown in transparent element resolution ([f657e6a](https://github.com/markuplint/markuplint/commit/f657e6a0156933c3acafb8e3975fbc31488b7cca)), closes [#3249](https://github.com/markuplint/markuplint/issues/3249)
+
+### BREAKING CHANGES
+
+- Remove the deprecated `attrs` option and the
+  `{ type: X }` value wrapper from `invalid-attr` rule options.
+
+* Remove `attrs` option (deprecated since v3.7.0)
+* Remove `{ type: X }` wrapper; specify type strings directly
+* Deprecate object format for `allowAttrs`/`disallowAttrs`
+* Unify value type validation via the types API
+
+- non-standard element/attribute detection moved from
+  deprecated-element to no-unsupported-features with checkNonStandard option.
+  Users of recommended preset are unaffected (auto-enabled via compat preset).
+- The `ignoreOmittedElements` option in the
+  `required-element` rule now defaults to `true` instead of `false`.
+  Ghost (omitted) elements implicitly created by the HTML parser
+  are no longer counted as satisfying the requirement by default.
+  Users who relied on the previous behavior should explicitly set
+  `ignoreOmittedElements: false`.
+- The end-tag rule now checks tagCloseChar for
+  self-closing detection instead of the removed selfClosingSolidus
+  property.
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
+# [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,64 @@
 import type { Translator } from '@markuplint/i18n';
 import type { Attribute as AttrSpec, AttributeType } from '@markuplint/ml-spec';
+import type { Type } from '@markuplint/types';
 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 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
+ * @param allAttrNames - Optional list of all valid attribute names for the element;
+ *   used to suggest a similar attribute name via Levenshtein distance when the attribute is 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, allAttrNames?: readonly string[]): 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 name
- * @param value
- * @param isCustomRule
- * @param spec
+ * @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 attrCheck(t: Translator, name: string, value: string, isCustomRule: boolean, spec?: AttrSpec): Invalid | Invalid<'invalid-value'>[] | false;
-export declare function valueCheck(t: Translator, name: string, value: string, type: ReadonlyDeep<AttributeType>): [string, Loc] | false;
+export declare function valueCheck(t: Translator, name: string, value: string, type: ReadonlyDeep<AttributeType | Type>): [string, Loc] | false;
 export {};

package/lib/attr-check.js

@@ -1,16 +1,29 @@
 import { toNonNullableArrayFromItemOrArray } from '@markuplint/shared';
-import { check } from '@markuplint/types';
+import { check, getCandidate } 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
+ * @param allAttrNames - Optional list of all valid attribute names for the element;
+ *   used to suggest a similar attribute name via Levenshtein distance when the attribute is 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) {
+export function attrCheck(t, name, value, isCustomRule, spec, allAttrNames) {
     if (!isCustomRule) {
         if (/^data-.+$/.test(name)) {
             // Ignore checking because "data-*" attribute is any type
@@ -30,9 +43,17 @@ export function attrCheck(t, name, value, isCustomRule, spec) {
     // Existence
     if (!spec) {
         log('The "%s" attribute DOES\'NT EXIST in the spec', name);
+        const baseMessage = t('{0} is {1:c}', t('the "{0*}" {1}', name, 'attribute'), 'disallowed');
+        const candidate = allAttrNames ? getCandidate(name, allAttrNames) : undefined;
+        if (candidate) {
+            return {
+                invalidType: 'non-existent',
+                message: baseMessage + t('. ') + t('Did you mean "{0*}"?', candidate),
+            };
+        }
         return {
             invalidType: 'non-existent',
-            message: t('{0} is {1:c}', t('the "{0*}" {1}', name, 'attribute'), 'disallowed'),
+            message: baseMessage,
         };
     }
     const nameCaseSensitive = /[A-Z]/.test(spec.name);
@@ -68,6 +89,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,12 @@
 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, as are bogus
+ * text nodes (e.g., orphaned end tags).
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<RuleConfigValue, undefined>>;
 export default _default;

package/lib/character-reference/index.js

@@ -1,12 +1,32 @@
 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, as are bogus
+ * text nodes (e.g., orphaned end tags).
+ */
 export default createRule({
     meta: meta,
     async verify({ document, report, t }) {
         const targetNodes = [];
         await document.walkOn('Text', node => {
+            if (node.isBogus) {
+                return;
+            }
             if (node.parentNode && ignoreParentElement.has(node.parentNode.nodeName.toLowerCase())) {
                 return;
             }

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/correct-aspect-ratio/index.d.ts

@@ -0,0 +1,5 @@
+type Options = {
+    readonly documentRoot?: string;
+};
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
+export default _default;