@markuplint/rules 4.11.2 → 4.18.0

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 }) {

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

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

package/lib/deprecated-attr/meta.js

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

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

@@ -1,2 +1,10 @@
+/**
+ * Rule that reports the use of deprecated, obsolete, or non-standard HTML
+ * elements.
+ *
+ * Walks HTML and SVG elements and checks their spec status. Reports any
+ * element that is marked as deprecated, obsolete, or non-standard in the
+ * HTML specification.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/deprecated-element/index.js

@@ -1,5 +1,13 @@
 import { createRule, getSpec } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that reports the use of deprecated, obsolete, or non-standard HTML
+ * elements.
+ *
+ * Walks HTML and SVG elements and checks their spec status. Reports any
+ * element that is marked as deprecated, obsolete, or non-standard in the
+ * HTML specification.
+ */
 export default createRule({
     meta: meta,
     async verify({ document, report, t }) {

package/lib/deprecated-element/meta.d.ts

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

package/lib/deprecated-element/meta.js

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

package/lib/disallowed-element/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Rule that disallows elements matching the configured CSS selectors.
+ *
+ * Accepts an array of selector strings as its value. Queries the document
+ * (and per-element overrides) for matching elements and reports each one
+ * as disallowed.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<string[], undefined>>;
 export default _default;

package/lib/disallowed-element/index.js

@@ -1,5 +1,12 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that disallows elements matching the configured CSS selectors.
+ *
+ * Accepts an array of selector strings as its value. Queries the document
+ * (and per-element overrides) for matching elements and reports each one
+ * as disallowed.
+ */
 export default createRule({
     meta: meta,
     defaultValue: [],

package/lib/disallowed-element/meta.d.ts

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

package/lib/disallowed-element/meta.js

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

package/lib/doctype/index.d.ts

@@ -1,5 +1,15 @@
+/** Configuration options for the doctype rule. */
 type Option = {
+    /** Whether to report obsolete doctypes that include a public or system identifier. */
     denyObsoleteType: boolean;
 };
+/**
+ * Rule that validates the presence and correctness of the document's DOCTYPE
+ * declaration.
+ *
+ * Reports an error when no DOCTYPE is found (skipped for document fragments)
+ * and when an obsolete DOCTYPE (one with a public or system identifier) is
+ * declared.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<"always", Option>>;
 export default _default;

package/lib/doctype/index.js

@@ -1,5 +1,13 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that validates the presence and correctness of the document's DOCTYPE
+ * declaration.
+ *
+ * Reports an error when no DOCTYPE is found (skipped for document fragments)
+ * and when an obsolete DOCTYPE (one with a public or system identifier) is
+ * declared.
+ */
 export default createRule({
     meta: meta,
     defaultValue: 'always',

package/lib/doctype/meta.d.ts

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

package/lib/doctype/meta.js

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

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

@@ -1,2 +1,9 @@
+/**
+ * Rule that checks for missing end tags on non-void HTML elements.
+ *
+ * Reports elements that are neither void nor self-closing and have no
+ * closing tag. Omitted elements and elements in documents configured
+ * with `endTag: 'never'` are excluded.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, undefined>>;
 export default _default;

package/lib/end-tag/index.js

@@ -1,6 +1,13 @@
 import { createRule } from '@markuplint/ml-core';
 import { isVoidElement } from '@markuplint/ml-spec';
 import meta from './meta.js';
+/**
+ * Rule that checks for missing end tags on non-void HTML elements.
+ *
+ * Reports elements that are neither void nor self-closing and have no
+ * closing tag. Omitted elements and elements in documents configured
+ * with `endTag: 'never'` are excluded.
+ */
 export default createRule({
     meta: meta,
     defaultSeverity: 'warning',

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

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

package/lib/end-tag/meta.js

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

package/lib/heading-levels/index.d.ts

@@ -1,2 +1,8 @@
+/**
+ * Rule that validates heading levels (h1-h6) are not skipped.
+ *
+ * Ensures that heading elements appear in a sequential order without
+ * gaps (e.g., an h4 must not follow an h2 directly without an h3 in between).
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, null>>;
 export default _default;

package/lib/heading-levels/index.js

@@ -1,5 +1,11 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that validates heading levels (h1-h6) are not skipped.
+ *
+ * Ensures that heading elements appear in a sequential order without
+ * gaps (e.g., an h4 must not follow an h2 directly without an h3 in between).
+ */
 export default createRule({
     meta: meta,
     defaultValue: true,

package/lib/heading-levels/meta.d.ts

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

package/lib/heading-levels/meta.js

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

package/lib/helpers.d.ts

@@ -4,7 +4,27 @@ import type { PlainData } from '@markuplint/ml-config';
 import type { Element, RuleConfigValue, Document } from '@markuplint/ml-core';
 import type { Attribute } from '@markuplint/ml-spec';
 import type { WritableDeep } from 'type-fest';
+/**
+ * Tests whether an element matches the condition specified in an attribute spec.
+ * When the condition is `null` or `undefined`, the element is considered to match unconditionally.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param node - The element to test against the condition
+ * @param condition - A CSS selector string or array of selector strings from the attribute specification;
+ *   if `null`/`undefined`, the function returns `true`
+ * @returns `true` if the element matches the condition (or no condition is given), `false` otherwise
+ */
 export declare function attrMatches<T extends RuleConfigValue, O extends PlainData>(node: Element<T, O>, condition: Attribute['condition']): boolean;
+/**
+ * Tests whether a string matches a given pattern. The pattern can be either
+ * a plain string (tested for exact equality) or a regular expression literal
+ * in the form `/pattern/flags`.
+ *
+ * @param needle - The string to test
+ * @param pattern - A plain string or a regex literal string (e.g. `/^foo/i`)
+ * @returns `true` if the needle matches the pattern
+ */
 export declare function match(needle: string, pattern: string): boolean;
 /**
  * PotentialCustomElementName
@@ -22,6 +42,22 @@ export declare function match(needle: string, pattern: string): boolean;
  * Originally, it is not possible to define a name including ASCII upper alphas in the custom element, but it is not treated as illegal by the HTML parser.
  */
 export declare const rePCENChar: string;
+/**
+ * Validates an attribute name/value pair against its specification.
+ * Checks attribute existence in the spec, value validity, conditional applicability,
+ * and skips validation for dynamic (template-interpolated) values when the error
+ * relates to an invalid value.
+ *
+ * @param t - The i18n translator for generating localized error messages
+ * @param name - The attribute name to validate
+ * @param value - The attribute value to validate
+ * @param isDynamicValue - Whether the value is dynamic (e.g. from a template expression);
+ *   if `true`, invalid-value errors are suppressed
+ * @param node - The element that owns the attribute
+ * @param attrSpecs - The list of attribute specifications to validate against
+ * @param log - Optional debug logger for diagnostic output
+ * @returns `false` if valid, or an `Invalid` object (or array of them) describing the violation
+ */
 export declare function isValidAttr(t: Translator, name: string, value: string, isDynamicValue: boolean, node: Element<any, any>, attrSpecs: readonly Attribute[], log?: Log): false | {
     invalidType: "non-existent" | "invalid-value" | "disallowed-attr";
     message: string;
@@ -39,14 +75,82 @@ export declare function isValidAttr(t: Translator, name: string, value: string,
         col: number;
     };
 }[];
+/**
+ * Normalizes an attribute value according to its specification rules.
+ * Applies case-folding, whitespace trimming, and separator normalization
+ * based on the attribute type definition.
+ *
+ * @param value - The raw attribute value to normalize
+ * @param spec - The attribute specification that defines normalization rules
+ *   (case sensitivity, separator type, whitespace handling)
+ * @returns The normalized attribute value
+ */
 export declare function toNormalizedValue(value: string, spec: Attribute): string;
+/**
+ * Determines whether an element's accessible name may change at runtime.
+ * Returns `true` if the element itself has mutable attributes or children,
+ * or if an associated `<label>` element has mutable content.
+ *
+ * @param el - The element whose accessible name stability is being checked
+ * @param document - The document containing the element, used to locate associated labels
+ * @returns `true` if the accessible name could change dynamically, `false` otherwise
+ */
 export declare function accnameMayBeMutable(el: Element<any, any>, document: Document<any, any>): boolean;
+/**
+ * Finds the `<label>` element associated with a labelable form element.
+ * First checks for an ancestor `<label>`, then looks for a `<label>` whose
+ * `for` attribute references the element's `id`. Returns `null` if the
+ * element is not labelable or no associated label is found.
+ *
+ * @template V - The rule configuration value type
+ * @template O - The rule options type
+ * @param el - The element to find a label for (must be a labelable element)
+ * @param document - The document to search for labels with a matching `for` attribute
+ * @returns The associated `<label>` element, or `null` if none is found
+ */
 export declare function getOwnedLabel<V extends RuleConfigValue, O extends PlainData>(el: Element<V, O>, document: Document<V, O>): Element<V, O> | null;
+/**
+ * A generic, null-safe collection backed by a `Set`.
+ * Automatically filters out `null` and `undefined` values when items are added.
+ * Implements the iterable protocol so it can be used in `for...of` loops.
+ *
+ * @template T - The type of items stored in the collection
+ */
 export declare class Collection<T> {
     #private;
+    /**
+     * Creates a new collection, optionally pre-populated with the given items.
+     * Any `null` or `undefined` values are silently ignored.
+     *
+     * @param items - Initial items to add to the collection
+     */
     constructor(...items: readonly (T | null | undefined)[]);
+    /**
+     * Returns an iterator over the items in the collection.
+     *
+     * @returns An iterator that yields each item in insertion order
+     */
     [Symbol.iterator](): Iterator<T>;
+    /**
+     * Adds one or more items to the collection.
+     * Any `null` or `undefined` values are silently ignored.
+     *
+     * @param items - Items to add to the collection
+     */
     add(...items: readonly (T | null | undefined)[]): void;
+    /**
+     * Returns a frozen array snapshot of the collection's contents.
+     *
+     * @returns A read-only array containing all items in insertion order
+     */
     toArray(): readonly T[];
 }
+/**
+ * Creates a deep, writable copy of the given value using structured cloning.
+ * Strips read-only modifiers from the result type so the clone can be freely mutated.
+ *
+ * @template T - The type of the value to clone
+ * @param value - The value to deep-copy
+ * @returns A mutable deep clone of the input value
+ */
 export declare function deepCopy<T>(value: T): WritableDeep<T>;

package/lib/helpers.js

@@ -7,6 +7,17 @@ var _Collection_items;
 // @ts-ignore
 import structuredClone from '@ungap/structured-clone';
 import { attrCheck } from './attr-check.js';
+/**
+ * Tests whether an element matches the condition specified in an attribute spec.
+ * When the condition is `null` or `undefined`, the element is considered to match unconditionally.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ * @param node - The element to test against the condition
+ * @param condition - A CSS selector string or array of selector strings from the attribute specification;
+ *   if `null`/`undefined`, the function returns `true`
+ * @returns `true` if the element matches the condition (or no condition is given), `false` otherwise
+ */
 export function attrMatches(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node, condition) {
@@ -16,6 +27,15 @@ node, condition) {
     const condSelector = typeof condition === 'string' ? condition : condition.join(',');
     return node.matches(condSelector);
 }
+/**
+ * Tests whether a string matches a given pattern. The pattern can be either
+ * a plain string (tested for exact equality) or a regular expression literal
+ * in the form `/pattern/flags`.
+ *
+ * @param needle - The string to test
+ * @param pattern - A plain string or a regex literal string (e.g. `/^foo/i`)
+ * @returns `true` if the needle matches the pattern
+ */
 export function match(needle, pattern) {
     const matches = pattern.match(/^\/(.*)\/([gim])*$/);
     if (matches && matches[1]) {
@@ -60,15 +80,30 @@ export const rePCENChar = [
     '[\uFDF0-\uFFFD]',
     '[\uD800-\uDBFF][\uDC00-\uDFFF]',
 ].join('|');
+/**
+ * Validates an attribute name/value pair against its specification.
+ * Checks attribute existence in the spec, value validity, conditional applicability,
+ * and skips validation for dynamic (template-interpolated) values when the error
+ * relates to an invalid value.
+ *
+ * @param t - The i18n translator for generating localized error messages
+ * @param name - The attribute name to validate
+ * @param value - The attribute value to validate
+ * @param isDynamicValue - Whether the value is dynamic (e.g. from a template expression);
+ *   if `true`, invalid-value errors are suppressed
+ * @param node - The element that owns the attribute
+ * @param attrSpecs - The list of attribute specifications to validate against
+ * @param log - Optional debug logger for diagnostic output
+ * @returns `false` if valid, or an `Invalid` object (or array of them) describing the violation
+ */
 export function isValidAttr(t, name, value, isDynamicValue, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node, attrSpecs, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 log) {
-    let invalid = false;
     const spec = attrSpecs.find(s => s.name.toLowerCase() === name.toLowerCase());
     log?.('Spec of the %s attr: %o', name, spec);
-    invalid = attrCheck(t, name, value, false, spec);
+    let invalid = attrCheck(t, name, value, false, spec);
     if (invalid === false &&
         spec &&
         spec.condition != null &&
@@ -84,6 +119,16 @@ log) {
     }
     return invalid;
 }
+/**
+ * Normalizes an attribute value according to its specification rules.
+ * Applies case-folding, whitespace trimming, and separator normalization
+ * based on the attribute type definition.
+ *
+ * @param value - The raw attribute value to normalize
+ * @param spec - The attribute specification that defines normalization rules
+ *   (case sensitivity, separator type, whitespace handling)
+ * @returns The normalized attribute value
+ */
 export function toNormalizedValue(value, spec) {
     let normalized = value;
     if (!spec.caseSensitive) {
@@ -112,6 +157,15 @@ export function toNormalizedValue(value, spec) {
     }
     return normalized;
 }
+/**
+ * Determines whether an element's accessible name may change at runtime.
+ * Returns `true` if the element itself has mutable attributes or children,
+ * or if an associated `<label>` element has mutable content.
+ *
+ * @param el - The element whose accessible name stability is being checked
+ * @param document - The document containing the element, used to locate associated labels
+ * @returns `true` if the accessible name could change dynamically, `false` otherwise
+ */
 export function accnameMayBeMutable(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, 
@@ -127,6 +181,18 @@ document) {
     return false;
 }
 const labelable = ['button', 'input:not([type=hidden])', 'meter', 'output', 'progress', 'select', 'textarea'];
+/**
+ * Finds the `<label>` element associated with a labelable form element.
+ * First checks for an ancestor `<label>`, then looks for a `<label>` whose
+ * `for` attribute references the element's `id`. Returns `null` if the
+ * element is not labelable or no associated label is found.
+ *
+ * @template V - The rule configuration value type
+ * @template O - The rule options type
+ * @param el - The element to find a label for (must be a labelable element)
+ * @param document - The document to search for labels with a matching `for` attribute
+ * @returns The associated `<label>` element, or `null` if none is found
+ */
 export function getOwnedLabel(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 el, 
@@ -144,14 +210,38 @@ document) {
     }
     return ownedLabel;
 }
+/**
+ * A generic, null-safe collection backed by a `Set`.
+ * Automatically filters out `null` and `undefined` values when items are added.
+ * Implements the iterable protocol so it can be used in `for...of` loops.
+ *
+ * @template T - The type of items stored in the collection
+ */
 export class Collection {
+    /**
+     * Creates a new collection, optionally pre-populated with the given items.
+     * Any `null` or `undefined` values are silently ignored.
+     *
+     * @param items - Initial items to add to the collection
+     */
     constructor(...items) {
         _Collection_items.set(this, new Set());
         this.add(...items);
     }
+    /**
+     * Returns an iterator over the items in the collection.
+     *
+     * @returns An iterator that yields each item in insertion order
+     */
     [(_Collection_items = new WeakMap(), Symbol.iterator)]() {
         return __classPrivateFieldGet(this, _Collection_items, "f").values();
     }
+    /**
+     * Adds one or more items to the collection.
+     * Any `null` or `undefined` values are silently ignored.
+     *
+     * @param items - Items to add to the collection
+     */
     add(...items) {
         for (const item of items) {
             if (item == null) {
@@ -160,10 +250,23 @@ export class Collection {
             __classPrivateFieldGet(this, _Collection_items, "f").add(item);
         }
     }
+    /**
+     * Returns a frozen array snapshot of the collection's contents.
+     *
+     * @returns A read-only array containing all items in insertion order
+     */
     toArray() {
         return Object.freeze([...__classPrivateFieldGet(this, _Collection_items, "f")]);
     }
 }
+/**
+ * Creates a deep, writable copy of the given value using structured cloning.
+ * Strips read-only modifiers from the result type so the clone can be freely mutated.
+ *
+ * @template T - The type of the value to clone
+ * @param value - The value to deep-copy
+ * @returns A mutable deep clone of the input value
+ */
 export function deepCopy(value) {
     return structuredClone(value);
 }

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

@@ -1,2 +1,9 @@
+/**
+ * Rule that checks for duplicate `id` attribute values within a document.
+ *
+ * Walks all elements and collects `id` values, reporting any that have
+ * already been seen. Dynamic values and directive attributes are excluded
+ * from the check.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<import("@markuplint/ml-core").RuleConfigValue, undefined>>;
 export default _default;

package/lib/id-duplication/index.js

@@ -1,5 +1,12 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that checks for duplicate `id` attribute values within a document.
+ *
+ * Walks all elements and collects `id` values, reporting any that have
+ * already been seen. Dynamic values and directive attributes are excluded
+ * from the check.
+ */
 export default createRule({
     meta: meta,
     async verify({ document, report, t }) {

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

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

package/lib/id-duplication/meta.js

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