@markuplint/rules 4.11.1 → 4.12.0

package/lib/permitted-contents/utils.js

@@ -13,6 +13,15 @@ var _Collection_locked, _Collection_matched, _Collection_nodes, _Collection_orig
 import { createSelector } from '@markuplint/selector';
 import { bgGreen, green, bgRed, bgBlue, blue, bgMagenta, cyan } from './debug.js';
 import { transparentMode } from './represent-transparent-nodes.js';
+/**
+ * Determines whether a given value is a terminal model (a selector string or an array
+ * of selector strings) rather than a nested array of content model patterns.
+ * Distinguishes between `Model` (leaf-level selectors) and `PermittedContentPattern[]`
+ * (structural pattern arrays that require further recursive evaluation).
+ *
+ * @param model - The value to check, either a terminal model or a nested pattern array.
+ * @returns True if the value is a terminal model (string or string array), false if it is a pattern array.
+ */
 export function isModel(model) {
     if (typeof model === 'string') {
         return true;
@@ -29,6 +38,16 @@ export function isModel(model) {
     }
     return modelMode;
 }
+/**
+ * Tests whether a child node matches a CSS selector string using the markuplint
+ * selector engine. Returns whether the node matched and, if not, the deepest
+ * unmatched descendant node for diagnostic purposes.
+ *
+ * @param selector - The CSS selector string to test against.
+ * @param node - The child node to test.
+ * @param specs - The spec data passed to the selector engine for attribute resolution.
+ * @returns An object with `matched: true` if the node matches, or `matched: false` with an optional `not` node.
+ */
 export function matches(selector, 
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 node, specs) {
@@ -48,6 +67,14 @@ node, specs) {
         not,
     };
 }
+/**
+ * Traverses a chain of nested `:has()` selector results to find the deepest
+ * descendant nodes that caused a selector mismatch. Used to provide precise
+ * error reporting by identifying the actual offending node in nested selectors.
+ *
+ * @param selectorResult - A matched selector result that may contain nested `:has()` results.
+ * @returns The deepest descendant child nodes from the nested selector chain.
+ */
 function descendants(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 selectorResult) {
@@ -58,6 +85,7 @@ selectorResult) {
                 nodes = dep.nodes;
                 continue;
             }
+            // eslint-disable-next-line no-useless-assignment
             selectorResult = dep;
             continue;
         }
@@ -65,24 +93,74 @@ selectorResult) {
     }
     return nodes;
 }
+/**
+ * Type guard that checks whether a content model pattern is a "require" pattern,
+ * indicating one or more required occurrences of a specific element or model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `require` property.
+ */
 export function isRequire(content) {
     return 'require' in content;
 }
+/**
+ * Type guard that checks whether a content model pattern is an "optional" pattern,
+ * indicating zero or one occurrences of a specific element or model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has an `optional` property.
+ */
 export function isOptional(content) {
     return 'optional' in content;
 }
+/**
+ * Type guard that checks whether a content model pattern is a "oneOrMore" pattern,
+ * indicating one or more occurrences of a specific element or model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `oneOrMore` property.
+ */
 export function isOneOrMore(content) {
     return 'oneOrMore' in content;
 }
+/**
+ * Type guard that checks whether a content model pattern is a "zeroOrMore" pattern,
+ * indicating zero or more occurrences of a specific element or model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `zeroOrMore` property.
+ */
 export function isZeroOrMore(content) {
     return 'zeroOrMore' in content;
 }
+/**
+ * Type guard that checks whether a content model pattern is a "choice" pattern,
+ * representing an alternation between multiple possible content model branches.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `choice` property.
+ */
 export function isChoice(content) {
     return 'choice' in content;
 }
+/**
+ * Type guard that checks whether a content model pattern is a "transparent" pattern,
+ * indicating the element inherits its parent's content model.
+ *
+ * @param content - The content model pattern to check.
+ * @returns True if the pattern has a `transparent` property.
+ */
 export function isTransparent(content) {
     return 'transparent' in content;
 }
+/**
+ * Normalizes a quantified content model pattern (require, optional, oneOrMore, or zeroOrMore)
+ * into a uniform representation with the inner model, minimum count, maximum count,
+ * a regex-like repeat sign for debug display, and the appropriate missing-node error type.
+ *
+ * @param pattern - A quantified content model pattern to normalize.
+ * @returns An object with `model`, `min`, `max`, `repeat` sign, and optional `missingType`.
+ */
 export function normalizeModel(pattern) {
     let model;
     let min;
@@ -137,6 +215,15 @@ export function normalizeModel(pattern) {
         missingType,
     };
 }
+/**
+ * Merges two Hints objects, combining their properties and selecting the
+ * `missing` hint with the higher `barelyMatchedElements` count (i.e., the
+ * one closest to a successful match) for the most useful error diagnostics.
+ *
+ * @param a - The first hints object.
+ * @param b - The second hints object.
+ * @returns A merged hints object with undefined properties removed.
+ */
 export function mergeHints(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
 a, 
@@ -149,6 +236,15 @@ b) {
         missing: missing && cleanObject(missing),
     });
 }
+/**
+ * Creates a shallow copy of an object with all `undefined` values removed.
+ * Used to produce clean hint objects for result reporting without
+ * extraneous undefined properties.
+ *
+ * @template T - The object type.
+ * @param object - The source object to clean.
+ * @returns A new object containing only the defined properties of the input.
+ */
 export function cleanObject(object) {
     const newObject = {};
     for (const [key, value] of Object.entries(object)) {
@@ -158,7 +254,20 @@ export function cleanObject(object) {
     }
     return newObject;
 }
+/**
+ * Tracks matched and unmatched child nodes during content model validation.
+ * Provides operations for adding matched nodes, backtracking to a locked state,
+ * capping matches at a maximum count, and generating colored debug output.
+ *
+ * The collection maintains an ordered set of original nodes and partitions them
+ * into matched and unmatched sets as the validation algorithm progresses.
+ */
 export class Collection {
+    /**
+     * Creates a new Collection from the given child nodes.
+     *
+     * @param origin - The initial list of child nodes to track.
+     */
     constructor(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     origin) {
@@ -169,18 +278,37 @@ export class Collection {
         __classPrivateFieldSet(this, _Collection_origin, [...origin], "f");
         __classPrivateFieldSet(this, _Collection_nodes, new Set(__classPrivateFieldGet(this, _Collection_origin, "f")), "f");
     }
+    /**
+     * Returns a copy of the currently matched nodes in insertion order.
+     */
     get matched() {
         return [...__classPrivateFieldGet(this, _Collection_matched, "f")];
     }
+    /**
+     * Returns the number of currently matched nodes.
+     */
     get matchedCount() {
         return __classPrivateFieldGet(this, _Collection_matched, "f").size;
     }
+    /**
+     * Returns a copy of all original nodes in their original order.
+     */
     get nodes() {
         return [...__classPrivateFieldGet(this, _Collection_origin, "f")];
     }
+    /**
+     * Returns the nodes that have not yet been matched, preserving original order.
+     */
     get unmatched() {
         return [...__classPrivateFieldGet(this, _Collection_nodes, "f")].filter(n => !__classPrivateFieldGet(this, _Collection_matched, "f").has(n));
     }
+    /**
+     * Adds nodes to the matched set. All nodes must belong to the original
+     * collection; external nodes will cause a ReferenceError.
+     *
+     * @param nodes - The child nodes to mark as matched.
+     * @returns True if the matched set grew (new nodes were added), false otherwise.
+     */
     addMatched(
     // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
     nodes) {
@@ -193,17 +321,43 @@ export class Collection {
         }
         return i < __classPrivateFieldGet(this, _Collection_matched, "f").size;
     }
+    /**
+     * Reverts the matched set to the last locked state, discarding
+     * any matches added since the last `lock()` call. Used for backtracking
+     * when a pattern match attempt fails after a zero-match.
+     */
     back() {
         __classPrivateFieldSet(this, _Collection_matched, new Set(__classPrivateFieldGet(this, _Collection_locked, "f")), "f");
     }
+    /**
+     * Saves the current matched set as a checkpoint that `back()` can
+     * revert to. Called after a successful backtrack recovery to preserve
+     * the known-good state.
+     */
     lock() {
         __classPrivateFieldSet(this, _Collection_locked, new Set(__classPrivateFieldGet(this, _Collection_matched, "f")), "f");
     }
+    /**
+     * Trims the matched set to at most `max` entries by removing
+     * the most recently added nodes beyond the limit. Used when the
+     * maximum occurrence count for a pattern is exceeded.
+     *
+     * @param max - The maximum number of matched nodes to retain.
+     */
     max(max) {
         const sliced = [...__classPrivateFieldGet(this, _Collection_matched, "f")].slice(max);
         for (const n of sliced)
             __classPrivateFieldGet(this, _Collection_matched, "f").delete(n);
     }
+    /**
+     * Returns a colored string representation of all nodes for debug logging.
+     * Matched nodes are shown in green, locked nodes in bold green, unmatched
+     * extra nodes in red (when highlighted), and transparent-mode nodes in
+     * blue/cyan/magenta variants.
+     *
+     * @param highlightExtraNodes - When true, unmatched nodes are highlighted in red/magenta.
+     * @returns A formatted string like `[ <div>, <span>, <p> ]` with ANSI colors.
+     */
     toString(highlightExtraNodes = false) {
         const out = [];
         for (const n of __classPrivateFieldGet(this, _Collection_origin, "f")) {
@@ -246,8 +400,23 @@ export class Collection {
     }
 }
 _Collection_locked = new WeakMap(), _Collection_matched = new WeakMap(), _Collection_nodes = new WeakMap(), _Collection_origin = new WeakMap();
+/**
+ * Error class representing an unsupported content model feature.
+ * Thrown when the validation engine encounters a pattern type or
+ * configuration that is not yet implemented.
+ */
 export class UnsupportedError extends Error {
 }
+/**
+ * Formats a content model (terminal model or pattern array) and its repeat sign
+ * into a regex-like string for debug logging output. Terminal selectors are
+ * rendered as `<selector>`, arrays of selectors as `(<s1>|<s2>)`, and
+ * nested patterns are recursively formatted.
+ *
+ * @param model - The model or pattern array to format.
+ * @param repeat - The quantifier sign to append (e.g., `+`, `*`, `?`, or `{m,n}`).
+ * @returns A human-readable regex-like string representation of the model.
+ */
 export function modelLog(model, repeat) {
     if (!isModel(model)) {
         return orderLog(model, repeat);
@@ -257,11 +426,28 @@ export function modelLog(model, repeat) {
     }
     return `(<${model.join('>|<')}>)${repeat}`;
 }
+/**
+ * Formats an ordered array of content model patterns into a regex-like
+ * string for debug logging, with an optional repeat quantifier wrapping
+ * the entire sequence.
+ *
+ * @param order - The ordered array of patterns to format.
+ * @param repeat - The quantifier sign to wrap around the sequence.
+ * @returns A formatted string representation of the ordered patterns.
+ */
 function orderLog(order, repeat) {
     return order.length === 1 && order[0]
         ? markRepeat(patternLog(order[0]), repeat)
         : markRepeat(order.map(pattern => patternLog(pattern)).join(''), repeat);
 }
+/**
+ * Formats a single content model pattern into a regex-like string for debug logging.
+ * Handles transparent, choice, and quantified patterns by dispatching to the
+ * appropriate formatting logic.
+ *
+ * @param pattern - The content model pattern to format.
+ * @returns A human-readable string representation of the pattern.
+ */
 function patternLog(pattern) {
     if (isTransparent(pattern)) {
         // 適当
@@ -273,6 +459,14 @@ function patternLog(pattern) {
     const { model, repeat } = normalizeModel(pattern);
     return modelLog(model, repeat);
 }
+/**
+ * Wraps a pattern string with parentheses and a repeat quantifier if a
+ * repeat sign is present. If no repeat sign is given, returns the pattern unchanged.
+ *
+ * @param pattern - The pattern string to wrap.
+ * @param repeat - The quantifier sign to append, or an empty string for no repetition.
+ * @returns The pattern string, optionally wrapped as `(pattern)quantifier`.
+ */
 function markRepeat(pattern, repeat) {
     return repeat ? `(${pattern})${repeat}` : pattern;
 }

package/lib/placeholder-label-option/index.d.ts

@@ -1,2 +1,9 @@
+/**
+ * Rule that validates required `<select>` elements have a placeholder label option.
+ *
+ * Per the HTML spec, a `<select>` with `required`, without `multiple`, and with a
+ * display size of 1 must have a placeholder label option (first `<option>` with
+ * an empty value directly under `<select>`).
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, undefined>>;
 export default _default;

package/lib/placeholder-label-option/index.js

@@ -1,5 +1,12 @@
 import { createRule } from '@markuplint/ml-core';
 import meta from './meta.js';
+/**
+ * Rule that validates required `<select>` elements have a placeholder label option.
+ *
+ * Per the HTML spec, a `<select>` with `required`, without `multiple`, and with a
+ * display size of 1 must have a placeholder label option (first `<option>` with
+ * an empty value directly under `<select>`).
+ */
 export default createRule({
     meta: meta,
     verify({ document, report, t }) {
@@ -18,13 +25,13 @@ export default createRule({
     },
 });
 /**
- * > If a select element has a required attribute specified,
- * > does not have a multiple attribute specified,
- * > and has a display size of 1,
- * > then the select element must have a placeholder label option.
+ * Determines whether a `<select>` element requires a placeholder label option.
  *
- * @param select
- * @returns
+ * Per the HTML spec, a select element needs a placeholder label option when it
+ * has `required`, does not have `multiple`, and has a display size of 1.
+ *
+ * @param select - The `<select>` element to evaluate.
+ * @returns `true` if the select element requires a placeholder label option.
  */
 function needPlaceholderLabelOption(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types
@@ -44,16 +51,13 @@ select) {
     return true;
 }
 /**
- * > If a select element has a required attribute specified,
- * > does not have a multiple attribute specified,
- * > and has a display size of 1;
- * > and if the value of the first option element
- * > in the select element's list of options (if any) is the empty string,
- * > and that option element's parent node is the select element (and not an optgroup element),
- * > then that option is the select element's **placeholder label option**.
+ * Checks whether a `<select>` element already has a valid placeholder label option.
+ *
+ * A placeholder label option is the first `<option>` whose value is the empty string
+ * and whose parent is the `<select>` element itself (not an `<optgroup>`).
  *
- * @param select
- * @returns
+ * @param select - The `<select>` element to check.
+ * @returns `true` if the element has a valid placeholder label option.
  */
 function hasPlaceholderLabelOption(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/placeholder-label-option/meta.d.ts

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

package/lib/placeholder-label-option/meta.js

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

package/lib/require-accessible-name/index.d.ts

@@ -1,6 +1,17 @@
 import type { ARIAVersion } from '@markuplint/ml-spec';
+/**
+ * Configuration options for the require-accessible-name rule.
+ */
 type Option = {
+    /** The ARIA specification version to use for role and accessible name computation. */
     ariaVersion: ARIAVersion;
 };
+/**
+ * Rule that requires elements with roles that need accessible names to have one.
+ *
+ * For each element exposed to the accessibility tree whose computed ARIA role
+ * has `accessibleNameRequired` set to `true`, this rule verifies that the element
+ * provides a non-empty accessible name.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Option>>;
 export default _default;

package/lib/require-accessible-name/index.js

@@ -2,6 +2,13 @@ import { createRule, getRoleSpec, getComputedRole } from '@markuplint/ml-core';
 import { ARIA_RECOMMENDED_VERSION, isExposed } from '@markuplint/ml-spec';
 import { accnameMayBeMutable } from '../helpers.js';
 import meta from './meta.js';
+/**
+ * Rule that requires elements with roles that need accessible names to have one.
+ *
+ * For each element exposed to the accessibility tree whose computed ARIA role
+ * has `accessibleNameRequired` set to `true`, this rule verifies that the element
+ * provides a non-empty accessible name.
+ */
 export default createRule({
     meta: meta,
     defaultOptions: {

package/lib/require-accessible-name/meta.d.ts

@@ -1,3 +1,4 @@
+/** Rule metadata for the `require-accessible-name` rule, categorized as accessibility. */
 declare const _default: {
     readonly category: "a11y";
 };

package/lib/require-accessible-name/meta.js

@@ -1,3 +1,4 @@
+/** Rule metadata for the `require-accessible-name` rule, categorized as accessibility. */
 export default {
     category: 'a11y',
 };

package/lib/require-datetime/index.d.ts

@@ -1,6 +1,18 @@
 import type { Lang } from './types.js';
+/**
+ * Configuration options for the require-datetime rule.
+ */
 type Options = {
+    /** Languages to use when parsing natural language date/time text content. */
     langs?: Lang[];
 };
+/**
+ * Rule that validates `<time>` elements without a `datetime` attribute have
+ * machine-readable date/time content.
+ *
+ * When a `<time>` element lacks the `datetime` attribute, this rule checks
+ * whether the text content is a valid datetime string. If not, it attempts
+ * to parse the content as natural language and suggests a `datetime` value.
+ */
 declare const _default: Readonly<import("@markuplint/ml-core").RuleSeed<boolean, Options>>;
 export default _default;

package/lib/require-datetime/index.js

@@ -2,6 +2,14 @@ import { createRule } from '@markuplint/ml-core';
 import { check } from '@markuplint/types';
 import meta from './meta.js';
 import { getCandidateDatetimeString } from './utils.js';
+/**
+ * Rule that validates `<time>` elements without a `datetime` attribute have
+ * machine-readable date/time content.
+ *
+ * When a `<time>` element lacks the `datetime` attribute, this rule checks
+ * whether the text content is a valid datetime string. If not, it attempts
+ * to parse the content as natural language and suggests a `datetime` value.
+ */
 export default createRule({
     meta: meta,
     defaultOptions: {

package/lib/require-datetime/meta.d.ts

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

package/lib/require-datetime/meta.js

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

package/lib/require-datetime/types.d.ts

@@ -1,10 +1,17 @@
+/** Union of possible date/time component keys used in parsed datetime data. */
 export type DateTimeKey = 'year' | 'month' | 'day' | 'hour' | 'minute' | 'second' | 'ms';
+/** A partial record mapping date/time component keys to their numeric values. */
 export type DateTimeData = Partial<Record<DateTimeKey, number>>;
+/** Represents a parsed date/time value with optional timezone offset. */
 export type DateTime = {
+    /** The parsed date/time component values. */
     datetime: DateTimeData;
+    /** Timezone offset in minutes from UTC (e.g., -300 for UTC-5). */
     zone?: number;
 };
 /**
+ * Supported locale codes for natural language date/time parsing.
+ *
  * @see https://github.com/wanasit/chrono#locales
  */
 export type Lang = 'en' | 'ja' | 'fr' | 'nl' | 'ru' | 'de' | 'pt' | 'zh';

package/lib/require-datetime/utils.d.ts

@@ -1,11 +1,24 @@
 import type { DateTime, Lang } from './types.js';
 /**
- * Datetime-ish text to a datetime data
+ * Parses natural language datetime text into structured datetime data.
  *
- * @param content
- * @param langs
- * @param base Reference date for a test
- * @returns
+ * Tries multiple locale parsers and returns the first successful parse result
+ * with only the certain (non-implied) date/time components included.
+ *
+ * @param content - The text content to parse as a datetime.
+ * @param langs - Locale codes to attempt parsing with.
+ * @param base - Optional reference date for relative date parsing (e.g., "tomorrow").
+ * @returns Parsed datetime data with timezone, or `null` if parsing fails.
  */
 export declare function parseADatetime(content: string, langs: readonly Lang[], base?: Readonly<Date>): DateTime | null;
+/**
+ * Generates an HTML `datetime` attribute value from natural language text.
+ *
+ * Parses the text content using chrono-node and formats the result as an
+ * ISO 8601-like datetime string suitable for the `datetime` attribute.
+ *
+ * @param content - The text content to parse.
+ * @param langs - Locale codes to use for parsing. Defaults to all supported languages.
+ * @returns A formatted datetime string, or `null` if the content cannot be parsed.
+ */
 export declare function getCandidateDatetimeString(content: string, langs?: Lang[]): string | null;

package/lib/require-datetime/utils.js

@@ -1,12 +1,16 @@
 import * as chrono from 'chrono-node';
+/** Default set of languages to try when parsing natural language datetime text. */
 const defaultLangs = ['en', 'ja', 'fr', 'nl', 'ru', 'de', 'pt', 'zh'];
 /**
- * Datetime-ish text to a datetime data
+ * Parses natural language datetime text into structured datetime data.
  *
- * @param content
- * @param langs
- * @param base Reference date for a test
- * @returns
+ * Tries multiple locale parsers and returns the first successful parse result
+ * with only the certain (non-implied) date/time components included.
+ *
+ * @param content - The text content to parse as a datetime.
+ * @param langs - Locale codes to attempt parsing with.
+ * @param base - Optional reference date for relative date parsing (e.g., "tomorrow").
+ * @returns Parsed datetime data with timezone, or `null` if parsing fails.
  */
 export function parseADatetime(content, langs, base) {
     const date = parseTryMultipleLangs(content, langs, base);
@@ -43,6 +47,16 @@ export function parseADatetime(content, langs, base) {
     }
     return datetime;
 }
+/**
+ * Generates an HTML `datetime` attribute value from natural language text.
+ *
+ * Parses the text content using chrono-node and formats the result as an
+ * ISO 8601-like datetime string suitable for the `datetime` attribute.
+ *
+ * @param content - The text content to parse.
+ * @param langs - Locale codes to use for parsing. Defaults to all supported languages.
+ * @returns A formatted datetime string, or `null` if the content cannot be parsed.
+ */
 export function getCandidateDatetimeString(content, langs = defaultLangs) {
     const date = parseADatetime(content, langs);
     if (!date) {
@@ -60,6 +74,15 @@ export function getCandidateDatetimeString(content, langs = defaultLangs) {
     }
     return datetimeStr;
 }
+/**
+ * Converts parsed datetime data into an ISO 8601-like string.
+ *
+ * Produces different formats depending on which components are present
+ * (e.g., date-only, time-only, or combined date-time).
+ *
+ * @param date - The parsed date/time component data.
+ * @returns A formatted datetime string, or `null` if the components do not match any known format.
+ */
 function toDatetimeString(date) {
     if (only(date, ['year', 'month'])) {
         return `${f(date.year, 4)}-${f(date.month, 2)}`;
@@ -90,6 +113,17 @@ function toDatetimeString(date) {
     }
     return null;
 }
+/**
+ * Attempts to parse datetime text using multiple locale parsers sequentially.
+ *
+ * Returns the parsed start component from the first locale that produces a
+ * valid result (non-range, single datetime).
+ *
+ * @param content - The text content to parse.
+ * @param langs - Locale codes to try in order.
+ * @param base - Optional reference date for relative date parsing.
+ * @returns The parsed start component, or `null` if no locale succeeds.
+ */
 function parseTryMultipleLangs(content, langs, base) {
     for (const lang of langs) {
         const results = 
@@ -111,6 +145,16 @@ function parseTryMultipleLangs(content, langs, base) {
     }
     return null;
 }
+/**
+ * Type guard that checks if the given datetime data contains only the specified keys.
+ *
+ * @template K - The array of datetime keys to check for.
+ * @template U - Union of the key types.
+ * @template R - The resulting narrowed type with required properties.
+ * @param date - The datetime data to check.
+ * @param keys - The keys that should be the only ones present.
+ * @returns `true` if the date contains only the specified keys (and narrows the type).
+ */
 function only(date, keys) {
     const list = Object.keys(date);
     for (const exists of list) {
@@ -121,11 +165,11 @@ function only(date, keys) {
     return true;
 }
 /**
- * Formatter
+ * Formats a number with zero-padding to the specified width.
  *
- * @param n
- * @param pad zero padding
- * @returns
+ * @param n - The number to format.
+ * @param pad - The minimum number of digits in the output string.
+ * @returns The zero-padded string representation.
  */
 function f(n, pad) {
     return n.toString(10).padStart(pad, '0');