@markuplint/rules 5.0.0-rc.2 → 5.0.0-rc.5

package/lib/consistent-table-row-length/index.js

@@ -0,0 +1,69 @@
+import { createRule } from '@markuplint/ml-core';
+import { findChildren } from '../table-row-column-alignment/find-children.js';
+import { Grid, getIndexes } from '../table-row-column-alignment/grid.js';
+import meta from './meta.js';
+/**
+ * Flags rows whose width disagrees with the table's base column count.
+ *
+ * Unlike the sibling splits of `table-row-column-alignment`, this is not a table model error:
+ * HTML LS §4.9.12.1 Step 7 grows `xwidth` to fit a wider row, and a narrower row is only a table
+ * model error where {@link import('../no-empty-table-track/index.js')} already catches it (a
+ * column no cell ever anchors to). A ragged table is nevertheless almost always a mistake, which
+ * is why this check exists and why it stays a `warning` rather than the `error` of its siblings.
+ *
+ * Skips a table that `no-table-cell-overlap` already reports on — once two cells claim the same
+ * slot, row widths derived from the grid model are no longer reliable.
+ */
+export default createRule({
+    meta,
+    defaultSeverity: 'warning',
+    verify({ document, report, t }) {
+        const tables = document.querySelectorAll('table');
+        for (const table of tables) {
+            const grid = new Grid(table);
+            if (grid.hasOverlapped()) {
+                continue;
+            }
+            const baseColLength = grid.getBaseColLength();
+            for (const row of grid.getRows()) {
+                if (row.anchorCount === 0) {
+                    continue;
+                }
+                const colLength = row.slots.length;
+                if (colLength === baseColLength) {
+                    continue;
+                }
+                const indexes = getIndexes(row.slots);
+                const cells = findChildren(row.element, 'th, td');
+                if (colLength > baseColLength) {
+                    const index = indexes.slice(baseColLength)[0];
+                    const unexpected = typeof index === 'number' ? cells[index] : null;
+                    if (!unexpected) {
+                        // The overshoot starts inside a spanned cell, so the `colspan` is the culprit.
+                        const spanStart = cells.findLast(cell => Number.parseInt(cell.getAttribute('colspan') ?? '1') > 1);
+                        const colSpan = spanStart?.getAttributeNode('colspan');
+                        if (!colSpan) {
+                            continue;
+                        }
+                        report({
+                            scope: colSpan,
+                            message: t('Exceeds the number of available {0}', 'columns'),
+                        });
+                        continue;
+                    }
+                    const diff = colLength - baseColLength;
+                    report({
+                        scope: unexpected,
+                        message: t('{0} extra {1} in {2}', t(`${diff}`), t(diff === 1 ? 'column' : 'columns'), t('a {0}', t('row'))),
+                    });
+                    continue;
+                }
+                const diff = baseColLength - colLength;
+                report({
+                    scope: row.element,
+                    message: t('{0} missing {1} in {2}', t(`${diff}`), t(diff === 1 ? 'column' : 'columns'), t('a {0}', t('row'))),
+                });
+            }
+        }
+    },
+});

package/lib/consistent-table-row-length/meta.d.ts

@@ -0,0 +1,4 @@
+declare const _default: {
+    readonly category: "structure";
+};
+export default _default;

package/lib/consistent-table-row-length/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'structure',
+};

package/lib/create-message.d.ts

@@ -2,32 +2,9 @@ import type { Translator } from '@markuplint/i18n';
 import type { AttributeType } from '@markuplint/ml-spec';
 import type { UnmatchedResult, Type } 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 | Type>, 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
+ * The double-underscore prefix marks this as exposed only for testing — not
+ * part of the stable public API.
  */
 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,17 +1,4 @@
 import { isList, isKeyword, isEnum, isNumber, isDirective, isPattern } 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;
@@ -31,18 +18,8 @@ export function createMessageValueExpected(t, baseTarget, type, matches) {
     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
+ * The double-underscore prefix marks this as exposed only for testing — not
+ * part of the stable public API.
  */
 export function __createMessageValueExpected(t, baseTarget, expected, matches) {
     let target = baseTarget;
@@ -226,17 +203,6 @@ 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) {
@@ -268,14 +234,6 @@ 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': {
@@ -298,15 +256,6 @@ 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,12 +1,4 @@
 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`).
- */
+/** Enable by setting `DEBUG` to include `ml-rules` (e.g. `DEBUG=ml-rules`). */
 export declare const log: debug.Debugger;

package/lib/debug.js

@@ -1,7 +1,3 @@
 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`).
- */
+/** Enable by setting `DEBUG` to include `ml-rules` (e.g. `DEBUG=ml-rules`). */
 export const log = debug('ml-rules');

package/lib/element-supports-aria-prop/index.d.ts

@@ -0,0 +1,12 @@
+import type { Options } from '../wai-aria/types.js';
+/**
+ * Split from the former `wai-aria-disallowed-props` rule (#3989): the ARIA in
+ * HTML element-specific `aria-*` restrictions alone. See
+ * `checkingElementSupportsAriaProp`'s JSDoc for the full spec citation.
+ *
+ * The former rule's `disallowSetImplicitProps` option gated this check; the
+ * split rule has no such option — disabling this rule entirely is how users
+ * opt out.
+ */
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
+export default _default;

package/lib/element-supports-aria-prop/index.js

@@ -0,0 +1,38 @@
+import { createRule, getComputedRole, ariaSpecs, getSpec } from '@markuplint/ml-core';
+import { ARIA_RECOMMENDED_VERSION } from '@markuplint/ml-spec';
+import { checkingElementSupportsAriaProp } from '../wai-aria/checkings/element-supports-aria-prop.js';
+import { defaultOptions } from '../wai-aria/default-options.js';
+import meta from './meta.js';
+/**
+ * Split from the former `wai-aria-disallowed-props` rule (#3989): the ARIA in
+ * HTML element-specific `aria-*` restrictions alone. See
+ * `checkingElementSupportsAriaProp`'s JSDoc for the full spec citation.
+ *
+ * The former rule's `disallowSetImplicitProps` option gated this check; the
+ * split rule has no such option — disabling this rule entirely is how users
+ * opt out.
+ */
+export default createRule({
+    meta,
+    defaultOptions,
+    async verify({ document, report }) {
+        await document.walkOn('Element', el => {
+            const elSpec = getSpec(el, document.specs.specs);
+            // Autonomous custom elements have no spec.<el>.jsonc entry and no
+            // element-specific restriction to enforce here.
+            if (!elSpec)
+                return;
+            if (!elSpec.globalAttrs['#ARIAAttrs'])
+                return;
+            const propAttrs = el.attributes.filter(attr => /^aria-/i.test(attr.name));
+            if (propAttrs.length === 0)
+                return;
+            const ariaVersion = el.rule.options?.version ?? document.ruleCommonSettings?.ariaVersion ?? ARIA_RECOMMENDED_VERSION;
+            const computed = getComputedRole(document.specs, el, ariaVersion);
+            const { props: propSpecs } = ariaSpecs(document.specs, ariaVersion);
+            for (const attr of propAttrs) {
+                report(checkingElementSupportsAriaProp({ attr, role: computed.role, propSpecs }));
+            }
+        });
+    },
+});

package/lib/form-attr-references-form/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Require the `form` attribute on a form-associated element to reference
+ * an actual `<form>` element by ID. Per HTML LS §4.10.18.6: "If
+ * specified, the value must be the ID of a form element in the
+ * element's tree." Existence of the ID itself is the responsibility of
+ * `no-refer-to-non-existent-id`; this rule only checks the element type
+ * when the ID resolves.
+ *
+ * @see https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fae-form
+ */
+declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, null>>;
+export default _default;

package/lib/form-attr-references-form/index.js

@@ -0,0 +1,64 @@
+import { createRule } from '@markuplint/ml-core';
+import meta from './meta.js';
+/**
+ * Form-associated elements (HTML LS §4.10.2). Listed elements may carry
+ * a `form` attribute that explicitly associates them with a `<form>`
+ * element; the implicit ancestor-based association is otherwise used.
+ *
+ * @see https://html.spec.whatwg.org/multipage/forms.html#category-listed
+ */
+const FORM_ASSOCIATED_SELECTOR = [
+    'button',
+    'fieldset',
+    'input',
+    'label',
+    'meter',
+    'object',
+    'output',
+    'progress',
+    'select',
+    'textarea',
+].join(',');
+/**
+ * Require the `form` attribute on a form-associated element to reference
+ * an actual `<form>` element by ID. Per HTML LS §4.10.18.6: "If
+ * specified, the value must be the ID of a form element in the
+ * element's tree." Existence of the ID itself is the responsibility of
+ * `no-refer-to-non-existent-id`; this rule only checks the element type
+ * when the ID resolves.
+ *
+ * @see https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fae-form
+ */
+export default createRule({
+    meta: meta,
+    defaultValue: true,
+    defaultOptions: null,
+    async verify({ document, report, t }) {
+        await document.walkOn('Element', el => {
+            if (!el.matches(FORM_ASSOCIATED_SELECTOR))
+                return;
+            if (el.pretenderContext?.type === 'pretender' && !el.hasAttribute('as'))
+                return;
+            const formAttr = el.getAttributeNode('form');
+            if (!formAttr)
+                return;
+            if (formAttr.isDynamicValue)
+                return;
+            const targetId = formAttr.value;
+            const target = [...document.querySelectorAll('[id]')].find(candidate => candidate.getAttribute('id') === targetId);
+            // Existence is checked by `no-refer-to-non-existent-id`. If the ID does not resolve
+            // here, leave that diagnostic to the dedicated rule and stay silent.
+            if (!target)
+                return;
+            if (target.localName !== 'form') {
+                report({
+                    scope: formAttr,
+                    line: formAttr.valueNode?.startLine,
+                    col: formAttr.valueNode?.startCol,
+                    raw: formAttr.valueNode?.raw,
+                    message: t('The "{0}" attribute on a form-associated element must reference a "{1}" element', 'form', 'form'),
+                });
+            }
+        });
+    },
+});

package/lib/{correct-aspect-ratio → form-attr-references-form}/meta.d.ts

@@ -1,4 +1,4 @@
 declare const _default: {
-    readonly category: "validation";
+    readonly category: "references";
 };
 export default _default;

package/lib/form-attr-references-form/meta.js

@@ -0,0 +1,3 @@
+export default {
+    category: 'references',
+};

package/lib/head-element-order/meta.d.ts

@@ -1,5 +1,5 @@
 declare const _default: {
-    readonly category: "style";
+    readonly category: "structure";
     readonly fixable: true;
 };
 export default _default;

package/lib/head-element-order/meta.js

@@ -1,4 +1,4 @@
 export default {
-    category: 'style',
+    category: 'structure',
     fixable: true,
 };

package/lib/helpers.d.ts

@@ -1,30 +1,16 @@
-import type { Log } from './debug.js';
-import type { Translator } from '@markuplint/i18n';
 import type { FixToken, IRuleFixer, PlainData, TextEdit } 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
- */
+/** A `null`/`undefined` condition means the attribute applies unconditionally. */
 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
+ * Conditions are evaluated against literal attribute values, so when a referenced
+ * attribute's value is dynamic (template-interpolated) the condition result is
+ * indeterminate and must not be used to report a violation.
  */
+export declare function conditionDependsOnDynamicAttr<T extends RuleConfigValue, O extends PlainData>(node: Element<T, O>, condition: NonNullable<Attribute['condition']>): boolean;
+/** `pattern` is a regex literal of the form `/pattern/flags` if it matches that shape, otherwise an exact string. */
 export declare function match(needle: string, pattern: string): boolean;
 /**
  * PotentialCustomElementName
@@ -42,127 +28,20 @@ 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;
-    loc?: {
-        raw: string;
-        line: number;
-        col: number;
-    };
-} | {
-    invalidType: "invalid-value";
-    message: string;
-    loc?: {
-        raw: string;
-        line: number;
-        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;
 export declare const labelable: string[];
-/**
- * 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
- */
+/** `null`/`undefined` items are silently dropped on add. */
 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
- */
+/** Strips read-only modifiers from the result type so the clone can be freely mutated. */
 export declare function deepCopy<T>(value: T): WritableDeep<T>;
-/**
- * Creates a fix that removes an entire attribute (name + value + surrounding whitespace).
- * Used by rules that need to remove a whole attribute from an element.
- *
- * @param fixer - The rule fixer instance for building TextEdits
- * @param attr - The attribute token parts to remove (from `spacesBeforeName` through `endQuote`)
- * @returns A TextEdit (or empty array if no valid tokens exist) that removes the attribute
- */
 export declare function removeAttr(fixer: IRuleFixer, attr: {
     readonly spacesBeforeName: FixToken | null;
     readonly nameNode: FixToken | null;
@@ -173,15 +52,6 @@ export declare function removeAttr(fixer: IRuleFixer, attr: {
     readonly valueNode: FixToken | null;
     readonly endQuote: FixToken | null;
 }): TextEdit | TextEdit[];
-/**
- * Creates a fix that removes only the value portion of an attribute
- * (equals sign, quotes, and value), keeping the attribute name.
- * Used by `no-boolean-attr-value` to convert `disabled="disabled"` to `disabled`.
- *
- * @param fixer - The rule fixer instance for building TextEdits
- * @param attr - The attribute token parts to remove (from `spacesBeforeEqual` through `endQuote`)
- * @returns A TextEdit (or empty array if no valid tokens exist) that removes the value portion
- */
 export declare function removeAttrValue(fixer: IRuleFixer, attr: {
     readonly spacesBeforeEqual: FixToken | null;
     readonly equal: FixToken | null;