@markuplint/ml-core 4.13.1 → 4.13.3

package/docs/rule-system.md

@@ -0,0 +1,270 @@
+# Rule System
+
+Detailed reference for the rule framework in `@markuplint/ml-core`.
+
+## Overview
+
+The rule framework handles the full lifecycle of lint rules: definition, configuration, mapping to nodes, execution, and violation collection. The key components are:
+
+- **RuleSeed** -- Rule definition type (verify/fix functions + defaults)
+- **MLRule** -- Rule execution class (wraps a seed with name and config resolution)
+- **MLRuleContext** -- Execution context for rules (document access, translation, violation reporting)
+- **RuleMapper** -- Maps rule configurations to specific DOM nodes based on selector specificity
+- **Ruleset** -- Extracts rules, nodeRules, and childNodeRules from Config
+
+## RuleSeed
+
+Source: `src/ml-rule/types.ts`
+
+The `RuleSeed<T, O>` type defines a rule's implementation.
+
+```typescript
+type RuleSeed<T extends RuleConfigValue = boolean, O extends PlainData = undefined> = {
+  readonly meta?: {
+    readonly category?: 'validation' | 'style' | 'naming-convention' | 'a11y' | 'maintainability';
+  };
+  readonly defaultSeverity?: Severity;
+  readonly defaultValue?: T;
+  readonly defaultOptions?: O;
+  verify(context: ProvidedContext<T, O>): void | Promise<void>;
+  fix?(context: ProvidedContext<T, O>): void | Promise<void>;
+};
+```
+
+### Category Values
+
+| Category              | Description                     |
+| --------------------- | ------------------------------- |
+| `'validation'`        | HTML standard compliance checks |
+| `'style'`             | Code style and formatting rules |
+| `'naming-convention'` | Naming convention enforcement   |
+| `'a11y'`              | Accessibility checks            |
+| `'maintainability'`   | Code maintainability rules      |
+
+### Default Values
+
+- `defaultSeverity` defaults to `'error'` if not specified
+- `defaultValue` defaults to `true` if not specified
+- `defaultOptions` defaults to `undefined`
+
+## createRule
+
+Source: `src/ml-rule/create-rule.ts`
+
+Factory function for type-safe rule seed creation:
+
+```typescript
+function createRule<T extends RuleConfigValue, O extends PlainData = undefined>(
+  seed: Readonly<RuleSeed<T, O>>,
+): RuleSeed<T, O>;
+```
+
+Returns the seed as-is. Serves primarily as a type helper for TypeScript inference.
+
+### Usage
+
+```typescript
+import { createRule } from '@markuplint/ml-core';
+
+export default createRule({
+  defaultSeverity: 'error',
+  defaultValue: true,
+  async verify({ document, report, t }) {
+    await document.walkOn('Element', el => {
+      if (/* violation condition */) {
+        report({ scope: el, message: t('Error message') });
+      }
+    });
+  },
+});
+```
+
+## MLRule
+
+Source: `src/ml-rule/ml-rule.ts`
+
+`MLRule<T, O>` wraps a `RuleSeed` with a name and provides configuration resolution and verification execution.
+
+### Constructor
+
+```typescript
+constructor(o: Readonly<RuleSeed<T, O>> & { readonly name: string })
+```
+
+### Properties
+
+| Property          | Type       | Description                                     |
+| ----------------- | ---------- | ----------------------------------------------- |
+| `name`            | `string`   | Rule identifier (e.g., `"attr-duplication"`)    |
+| `defaultSeverity` | `Severity` | Default severity level (from seed or `'error'`) |
+| `defaultValue`    | `T`        | Default config value (from seed or `true`)      |
+| `defaultOptions`  | `O`        | Default options (from seed)                     |
+
+### Methods
+
+#### `verify(document, locale, fix): Promise<Violation[]>`
+
+Executes the rule against a document.
+
+**Flow:**
+
+1. `document.setRule(this)` -- sets current rule context on document
+2. `new MLRuleContext(document, locale)` -- creates execution context
+3. `context.provide()` -- generates providable context object
+4. `await seed.verify(context)` -- runs verification
+5. `await seed.fix(context)` -- runs fix (if `fix=true` and fix function exists)
+6. `context.reports` -> `Violation[]` -- maps reports to violations
+7. `document.setRule(null)` -- clears rule context
+
+**Report -> Violation mapping:**
+
+- Scope-based reports: extracts `line`, `col`, `raw` from `report.scope` (the node), severity from `report.scope.rule.severity`
+- Direct reports: uses `report.line`, `report.col`, `report.raw` directly, severity from `document.rule.severity`
+
+#### `getRuleInfo(ruleSet, ruleName): GlobalRuleInfo<T, O>`
+
+Resolves the full rule information from a ruleset.
+
+Returns:
+
+```typescript
+{
+  ...RuleInfo<T, O>,               // Global rule config
+  nodeRules: RuleInfo<T, O>[],     // Non-disabled node-level overrides
+  childNodeRules: RuleInfo<T, O>[], // Non-disabled child-node-level overrides
+}
+```
+
+#### `optimizeOption(configSettings): RuleInfo<T, O>`
+
+Normalizes raw rule settings into resolved `RuleInfo`.
+
+| Input                  | Result                                                                                  |
+| ---------------------- | --------------------------------------------------------------------------------------- |
+| `undefined` or `false` | `{ disabled: true, severity: default, value: default, options: default }`               |
+| `true`                 | `{ disabled: false, severity: default, value: default, options: default }`              |
+| `RuleConfig` object    | `{ disabled: false, severity: config/default, value: config/default, options: merged }` |
+| Primitive value        | `{ disabled: false, severity: default, value: input, options: default }`                |
+
+Options merging: arrays are spread (`[...a, ...b]`), objects are spread (`{...a, ...b}`), otherwise fallback to `b ?? a`.
+
+## MLRuleContext
+
+Source: `src/ml-rule/ml-rule-context.ts`
+
+`MLRuleContext<T, O>` provides the execution context for rules.
+
+### Constructor
+
+```typescript
+constructor(document: MLDocument<T, O>, locale: LocaleSet)
+```
+
+Creates translator from locale, stores document reference.
+
+### Properties
+
+| Property    | Type               | Description                 |
+| ----------- | ------------------ | --------------------------- |
+| `document`  | `MLDocument<T, O>` | The document being verified |
+| `locale`    | `string`           | Locale string               |
+| `translate` | `Translator`       | i18n message translator     |
+
+### `provide(): ProvidedContext`
+
+Returns the context object passed to `RuleSeed.verify()` and `RuleSeed.fix()`:
+
+```typescript
+{
+  document: MLDocument<T, O>,
+  translate: Translator,
+  t: Translator,        // alias for translate
+  reports: Report<T, O>[],
+  report: (report) => void | boolean,
+}
+```
+
+### `report(report)`
+
+Two overloads:
+
+1. **Direct report** (`Report<T, O>`): Pushes the report directly. Returns `undefined`.
+2. **Checker report** (`CheckerReport<T, O>`): Calls the function with translator. If it returns a report, pushes it and returns `true`. If `null`/`undefined`, returns `false`.
+
+### Deduplication
+
+Reports are deduplicated in `_push()` using:
+
+- **Scope-based**: same `scope` object + same `message`
+- **Position-based**: same `col` + `line` + `message` + `raw`
+
+### Message Finalization
+
+For English locale (`'en'`), the first lowercase letter is capitalized. Other locales pass through unchanged.
+
+## Checker Types
+
+Source: `src/ml-rule/types.ts`
+
+Utility types for building checker functions:
+
+| Type                      | Signature                                                    | Description                |
+| ------------------------- | ------------------------------------------------------------ | -------------------------- |
+| `Checker<T, O, P>`        | `(params: P) => CheckerReport<T, O>`                         | Generic checker            |
+| `ElementChecker<T, O, P>` | `(params: P & { el: Element<T, O> }) => CheckerReport<T, O>` | Element-specific checker   |
+| `AttrChecker<T, O, P>`    | `(params: P & { attr: Attr<T, O> }) => CheckerReport<T, O>`  | Attribute-specific checker |
+| `CheckerReport<T, O>`     | `(t: Translator) => Report<T, O> \| undefined \| null`       | Deferred report function   |
+
+## Rule Mapping
+
+For detailed documentation on `RuleMapper`, rule configuration resolution (three-layer processing with `rules`, `nodeRules`, `childNodeRules`), specificity-based conflict resolution, merging behavior, and regex selector templates, see the dedicated [Rule Mapping](./ml-dom/rule-mapping.md) reference.
+
+## Ruleset
+
+Source: `src/ruleset/index.ts`
+
+Extracts rule configuration from a `Config` object.
+
+```typescript
+class Ruleset {
+  readonly rules: Rules;
+  readonly nodeRules: readonly NodeRule[];
+  readonly childNodeRules: readonly ChildNodeRule[];
+
+  constructor(config: Config);
+}
+```
+
+- `rules` -- Global rule definitions (from `config.rules`, defaults to `{}`)
+- `nodeRules` -- Node-specific overrides (from `config.nodeRules`, defaults to `[]`)
+- `childNodeRules` -- Child-node-specific overrides (from `config.childNodeRules`, defaults to `[]`)
+
+## Test Utilities
+
+Source: `src/ml-rule/create-test-rule.ts`
+
+### createTestRule
+
+```typescript
+function createRule<T, O>(seed: Readonly<RuleSeed<T, O>> & { readonly name: string }): MLRule<T, O>;
+```
+
+Creates an `MLRule` instance for testing. Unlike `createRule()` in `create-rule.ts`, this requires a `name` property and returns an actual `MLRule` instance.
+
+### Test Pattern
+
+```typescript
+import { createRule } from '@markuplint/ml-core/test';
+import { createTestDocument } from '@markuplint/ml-core/test';
+
+const rule = createRule({
+  name: 'my-rule',
+  defaultSeverity: 'error',
+  async verify({ document, report, t }) {
+    // verification logic
+  },
+});
+
+const doc = createTestDocument('<div></div>');
+const violations = await rule.verify(doc, { locale: 'en' }, false);
+```

package/lib/convert-ruleset.d.ts

@@ -1,3 +1,10 @@
 import type { Config } from '@markuplint/ml-config';
 import { Ruleset } from './ruleset/index.js';
+/**
+ * Converts a markuplint {@link Config} object into a {@link Ruleset} instance
+ * that can be used by the linting engine.
+ *
+ * @param config - The configuration to convert (defaults to an empty config)
+ * @returns A new Ruleset instance
+ */
 export declare function convertRuleset(config?: Config): Ruleset;

package/lib/convert-ruleset.js

@@ -1,4 +1,11 @@
 import { Ruleset } from './ruleset/index.js';
+/**
+ * Converts a markuplint {@link Config} object into a {@link Ruleset} instance
+ * that can be used by the linting engine.
+ *
+ * @param config - The configuration to convert (defaults to an empty config)
+ * @returns A new Ruleset instance
+ */
 export function convertRuleset(config = {}) {
     return new Ruleset(config);
 }

package/lib/debug.d.ts

@@ -1,3 +1,7 @@
 import debug from 'debug';
 export declare const log: debug.Debugger;
+/**
+ * Enables debug logging for the `ml-core` namespace and the CLI namespace.
+ * No-op if debug logging is already enabled.
+ */
 export declare function enableDebug(): void;

package/lib/debug.js

@@ -1,6 +1,10 @@
 import debug from 'debug';
 const CLI_NS = 'markuplint-cli';
 export const log = debug('ml-core');
+/**
+ * Enables debug logging for the `ml-core` namespace and the CLI namespace.
+ * No-op if debug logging is already enabled.
+ */
 export function enableDebug() {
     if (!log.enabled) {
         debug.enable(`${log.namespace}*`);

package/lib/ml-core.d.ts

@@ -2,17 +2,53 @@ import type { MLFabric } from './types.js';
 import type { PlainData, RuleConfigValue, Violation } from '@markuplint/ml-config';
 import { ParserError } from '@markuplint/parser-utils';
 import { Document } from './ml-dom/index.js';
+/**
+ * Parameters for constructing an {@link MLCore} instance.
+ * Extends {@link MLFabric} with the source code, filename, and debug flag.
+ */
 export type MLCoreParams = {
+    /** The markup source code to lint */
     readonly sourceCode: string;
+    /** The filename associated with the source code */
     readonly filename: string;
+    /** Whether to enable debug logging */
     readonly debug?: boolean;
 } & MLFabric;
+/**
+ * The core linting engine for markuplint.
+ *
+ * Parses markup source code into an AST, constructs a DOM document,
+ * and verifies it against configured rules to produce violations.
+ */
 export declare class MLCore {
     #private;
     constructor({ parser, sourceCode, ruleset, rules, locale, schemas, parserOptions, severity, pretenders, filename, debug, configErrors, }: MLCoreParams);
+    /**
+     * The parsed document, or a {@link ParserError} if parsing failed.
+     */
     get document(): ParserError | Document<RuleConfigValue, PlainData>;
+    /**
+     * Replaces the source code and re-parses the document.
+     *
+     * @param sourceCode - The new markup source code
+     */
     setCode(sourceCode: string): void;
+    /**
+     * Updates the linting configuration and re-creates the document.
+     * Only re-parses if parser options have changed.
+     *
+     * @param fabric - Partial fabric with the properties to update
+     */
     update({ parser, ruleset, rules, locale, schemas, parserOptions, configErrors }: Partial<MLFabric>): void;
+    /**
+     * Runs all configured rules against the parsed document and returns violations.
+     *
+     * If the document failed to parse, a single parse-error violation is returned
+     * (unless parse errors are suppressed via severity options).
+     *
+     * @param fix - Whether to attempt auto-fixing violations
+     * @returns An array of violations found during verification
+     */
     verify(fix?: boolean): Promise<Violation[]>;
     private _createDocument;
     private _createParseError;

package/lib/ml-core.js

@@ -14,6 +14,12 @@ import { ParserError } from '@markuplint/parser-utils';
 import { log, enableDebug } from './debug.js';
 import { Document } from './ml-dom/index.js';
 const resultLog = log.extend('result');
+/**
+ * The core linting engine for markuplint.
+ *
+ * Parses markup source code into an AST, constructs a DOM document,
+ * and verifies it against configured rules to produce violations.
+ */
 export class MLCore {
     constructor({ parser, sourceCode, ruleset, rules, locale, schemas, parserOptions, severity, pretenders, filename, debug, configErrors, }) {
         _MLCore_ast.set(this, null);
@@ -50,14 +56,28 @@ export class MLCore {
         this._parse();
         this._createDocument();
     }
+    /**
+     * The parsed document, or a {@link ParserError} if parsing failed.
+     */
     get document() {
         return __classPrivateFieldGet(this, _MLCore_document, "f");
     }
+    /**
+     * Replaces the source code and re-parses the document.
+     *
+     * @param sourceCode - The new markup source code
+     */
     setCode(sourceCode) {
         __classPrivateFieldSet(this, _MLCore_sourceCode, sourceCode, "f");
         this._parse();
         this._createDocument();
     }
+    /**
+     * Updates the linting configuration and re-creates the document.
+     * Only re-parses if parser options have changed.
+     *
+     * @param fabric - Partial fabric with the properties to update
+     */
     update({ parser, ruleset, rules, locale, schemas, parserOptions, configErrors }) {
         __classPrivateFieldSet(this, _MLCore_parser, parser ?? __classPrivateFieldGet(this, _MLCore_parser, "f"), "f");
         __classPrivateFieldSet(this, _MLCore_ruleset, {
@@ -76,6 +96,15 @@ export class MLCore {
         }
         this._createDocument();
     }
+    /**
+     * Runs all configured rules against the parsed document and returns violations.
+     *
+     * If the document failed to parse, a single parse-error violation is returned
+     * (unless parse errors are suppressed via severity options).
+     *
+     * @param fix - Whether to attempt auto-fixing violations
+     * @returns An array of violations found during verification
+     */
     async verify(fix = false) {
         log('verify: start');
         const violations = [];

package/lib/ml-dom/helper/get-indent.d.ts

@@ -1,9 +1,12 @@
 import type { MLNode } from '../node/node.js';
 import type { MLText } from '../node/text.js';
 /**
+ * Computes the indentation preceding the given node by analyzing
+ * the whitespace in adjacent text nodes.
  *
  * @deprecated
- * @param node
+ * @param node - The node whose indentation to determine
+ * @returns An indentation object describing the whitespace, or null if no indentation is found
  */
 export declare function getIndent(node: MLNode<any, any>): MLDOMIndentation | null;
 declare class MLDOMIndentation {

package/lib/ml-dom/helper/get-indent.js

@@ -11,9 +11,12 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _MLDOMIndentation_fixed, _MLDOMIndentation_node, _MLDOMIndentation_parent;
 /**
+ * Computes the indentation preceding the given node by analyzing
+ * the whitespace in adjacent text nodes.
  *
  * @deprecated
- * @param node
+ * @param node - The node whose indentation to determine
+ * @returns An indentation object describing the whitespace, or null if no indentation is found
  */
 export function getIndent(
 // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types

package/lib/ml-dom/node/attr.d.ts

@@ -5,24 +5,69 @@ import type { PlainData, RuleConfigValue } from '@markuplint/ml-config';
 import { MLToken } from '../token/token.js';
 import { MLDomTokenList } from './dom-token-list.js';
 import { MLNode } from './node.js';
+/**
+ * Represents a DOM Attr (attribute) node wrapper in the markuplint DOM tree.
+ * Wraps an AST attribute token and provides access to the attribute's name, value,
+ * tokens (name, equal sign, quotes, value), and metadata such as whether
+ * the attribute is a directive or has a dynamic value.
+ *
+ * @template T - The rule configuration value type
+ * @template O - The rule options type
+ */
 export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = undefined> extends MLNode<T, O, MLASTAttr> implements Attr {
     #private;
+    /**
+     * A candidate attribute name suggested by the parser, if available.
+     */
     readonly candidate?: string;
+    /**
+     * The end quote token of the attribute value, or null if the attribute has no value or quotes.
+     */
     readonly endQuote: MLToken | null;
+    /**
+     * The equal sign token between the attribute name and value, or null if absent.
+     */
     readonly equal: MLToken | null;
+    /**
+     * Whether this attribute is a directive (e.g., framework-specific attributes like `v-if` or `@click`).
+     */
     readonly isDirective?: true;
+    /**
+     * Whether this attribute can be duplicated on the same element.
+     */
     readonly isDuplicatable: boolean;
+    /**
+     * Whether this attribute has a dynamic value (e.g., a template expression rather than a static string).
+     */
     readonly isDynamicValue?: true;
+    /**
+     * The token representing the attribute name, or null for spread attributes.
+     */
     readonly nameNode: MLToken | null;
     /**
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-node-previoussibling%E2%91%A0
      */
     readonly ownerElement: MLElement<T, O>;
+    /**
+     * The whitespace token after the equal sign, or null if absent.
+     */
     readonly spacesAfterEqual: MLToken | null;
+    /**
+     * The whitespace token before the equal sign, or null if absent.
+     */
     readonly spacesBeforeEqual: MLToken | null;
+    /**
+     * The whitespace token before the attribute name, or null if absent.
+     */
     readonly spacesBeforeName: MLToken | null;
+    /**
+     * The start quote token of the attribute value, or null if the attribute has no value or quotes.
+     */
     readonly startQuote: MLToken | null;
+    /**
+     * The token representing the attribute value, or null if the attribute has no value.
+     */
     readonly valueNode: MLToken | null;
     /**
      * Returns the "string" if HTML syntax. Otherwise, returns a type in its syntax.
@@ -31,25 +76,30 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      * @implements `@markuplint/ml-core` API: `MLAttr`
      */
     readonly valueType: 'string' | 'number' | 'boolean' | 'code';
+    /**
+     * Creates a new MLAttr instance from an AST attribute token.
+     *
+     * @param astToken - The AST attribute token to wrap
+     * @param ownElement - The element that owns this attribute
+     */
     constructor(astToken: MLASTAttr, ownElement: MLElement<T, O>);
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * Returns the local name portion of the attribute (without namespace prefix).
      *
-     * @unsupported
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-attr-localname
      */
     get localName(): string;
     /**
+     * Returns the qualified attribute name (the potential name resolved by the parser).
      *
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#dom-attr-name
      */
     get name(): string;
     /**
-     * **IT THROWS AN ERROR WHEN CALLING THIS.**
+     * Returns the namespace URI of this attribute, resolved from the attribute name.
      *
-     * @unsupported
      * @implements DOM API: `Attr`
      * @see https://dom.spec.whatwg.org/#ref-for-dom-attr-namespaceuri
      */
@@ -64,6 +114,12 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      * Returns a number appropriate for the type of `Attr`
      */
     get nodeType(): AttributeNodeType;
+    /**
+     * Returns the attribute value, equivalent to the `value` property.
+     *
+     * @implements DOM API: `Attr`
+     * @see https://dom.spec.whatwg.org/#dom-node-nodevalue
+     */
     get nodeValue(): string;
     /**
      * **IT THROWS AN ERROR WHEN CALLING THIS.**
@@ -106,7 +162,12 @@ export declare class MLAttr<T extends RuleConfigValue, O extends PlainData = und
      */
     fix(raw: string): void;
     /**
+     * Returns a normalized string representation of the attribute,
+     * stripping extraneous whitespace around the name, equal sign, and value tokens.
+     * Falls back to the raw string if any token is missing.
+     *
      * @implements `@markuplint/ml-core` API: `MLAttr`
+     * @returns The normalized attribute string
      */
     toNormalizeString(): string;
     /**