@markuplint/ml-core 4.13.2 → 4.13.3

package/docs/ml-dom/rule-mapping.md

@@ -0,0 +1,371 @@
+# Rule Mapping — How Rules Are Applied to Nodes
+
+**Source:** `src/ml-dom/node/document.ts` (`_ruleMapping()`), `src/ml-dom/node/rule-mapper.ts` (`RuleMapper`)
+
+## Overview
+
+Rule mapping is the process of distributing rule configurations from the user's config to individual MLDOM nodes. Each node has a `rules` property (`Record<string, AnyRule>`) that stores the resolved rule configuration for every rule that applies to it.
+
+The mapping uses three configuration layers — `rules`, `nodeRules`, and `childNodeRules` — processed in a defined order, with CSS selector specificity used to resolve conflicts.
+
+For configuration syntax, see the [markuplint configuration documentation](https://markuplint.dev/docs/configuration).
+
+## Architecture
+
+### When Rule Mapping Happens
+
+Rule mapping happens **once** during `MLDocument` construction, after pretender initialization and before any rule execution:
+
+```
+MLDocument constructor
+  ├── 1. Parse AST → create MLDOM nodes (nodeList)
+  ├── 2. _pretending(pretenders)
+  ├── 3. _ruleMapping(ruleset)            ← Rule mapping
+  └── 4. (ready for rule verification)
+```
+
+This ordering matters:
+
+- Pretenders must be established first, so that selector matching in rule mapping can match against pretender identities (e.g., a `nodeRules` entry targeting `button` should match `<MyButton>` pretending to be `<button>`)
+- Rule mapping must complete before verification, so that rules can read `node.rules` during `walkOn()`
+
+### Components
+
+| Component        | Source                           | Role                                                                      |
+| ---------------- | -------------------------------- | ------------------------------------------------------------------------- |
+| `Ruleset`        | `src/ruleset/index.ts`           | Extracts `rules`, `nodeRules`, `childNodeRules` from user config          |
+| `RuleMapper`     | `src/ml-dom/node/rule-mapper.ts` | Accumulates rule-to-node mappings with specificity, applies them to nodes |
+| `_ruleMapping()` | `src/ml-dom/node/document.ts`    | Orchestrates the three-layer processing                                   |
+
+## The Three Layers
+
+### Layer 1: Global Rules (`rules`)
+
+```json
+{
+  "rules": {
+    "attr-duplication": true,
+    "case-sensitive-tag-name": "warning"
+  }
+}
+```
+
+Global rules are applied to **every node** in the document, including the `#document` node itself. They have a fixed specificity of `[0, 0, 0]`.
+
+**Processing:**
+
+```typescript
+// Apply to #document
+for (const ruleName of Object.keys(ruleset.rules)) {
+  ruleMapper.set(document, ruleName, {
+    from: 'rules',
+    specificity: [0, 0, 0],
+    rule,
+  });
+}
+
+// Apply to every node in nodeList
+for (const node of document.nodeList) {
+  for (const ruleName of Object.keys(ruleset.rules)) {
+    ruleMapper.set(node, ruleName, {
+      from: 'rules',
+      specificity: [0, 0, 0],
+      rule,
+    });
+  }
+}
+```
+
+### Layer 2: Node Rules (`nodeRules`)
+
+```json
+{
+  "nodeRules": [
+    {
+      "selector": "img",
+      "rules": {
+        "required-attr": { "value": "alt" }
+      }
+    }
+  ]
+}
+```
+
+Node rules override global rules for **elements that match the selector**. Only `ELEMENT_NODE` and `TEXT_NODE` are considered; text nodes cannot be selector targets, so only elements are actually matched.
+
+**Processing:**
+
+1. For each `nodeRule` entry, check if the current element matches via `matchMLSelector(selector)`
+2. If matched, for each rule in the entry:
+   - `exchangeValueOnRule(rule, matches.data)` — render Mustache template variables from regex selector captures
+   - `mergeRule(globalRule, convertedRule)` — merge with the global rule config (see [Merging](#merging-with-global-rules))
+   - `ruleMapper.set(node, ruleName, { from: 'nodeRules', specificity: matches.specificity, rule: mergedRule })`
+
+The specificity comes from the CSS selector used to match the element.
+
+### Layer 3: Child Node Rules (`childNodeRules`)
+
+```json
+{
+  "childNodeRules": [
+    {
+      "selector": "table",
+      "inheritance": true,
+      "rules": {
+        "class-naming": "/^table-/"
+      }
+    }
+  ]
+}
+```
+
+Child node rules apply rules to **children (or descendants)** of matched elements. The selector matches the **parent**, and the rules are distributed to its children.
+
+**Processing:**
+
+1. For each `childNodeRule` entry, check if the current element matches via `matchMLSelector(selector)`
+2. If matched, determine the target nodes:
+   - `inheritance: true` → all **descendants** (collected via `syncWalk`)
+   - `inheritance: false` (default) → only **direct children** (`childNodes`)
+3. For each rule in the entry, apply the merged rule to every target node
+
+```typescript
+const targetDescendants = nodeRule.inheritance ? descendants : children;
+
+for (const descendant of targetDescendants) {
+  ruleMapper.set(descendant, ruleName, {
+    from: 'childNodeRules',
+    specificity: matches.specificity,
+    rule: mergedRule,
+  });
+}
+```
+
+Note: the specificity is that of the **parent's** selector match, not the child's.
+
+## Processing Order
+
+The three layers are processed in a specific order within `_ruleMapping()`:
+
+```
+For the #document node:
+  1. Apply all global rules (specificity [0,0,0])
+
+For each node in nodeList:
+  2. Apply all global rules (specificity [0,0,0])
+  3. Apply matching nodeRules (selector specificity)
+  4. Apply matching childNodeRules (selector specificity of parent)
+```
+
+Because `RuleMapper.set()` resolves conflicts by specificity, the processing order within the same specificity level matters:
+
+- **Same specificity**: later `set()` calls overwrite earlier ones (last-write-wins)
+- **Higher specificity**: always wins regardless of order
+- **Lower specificity**: silently skipped
+
+This means:
+
+| Scenario                                                                 | Winner                                                     |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `rules` vs `nodeRules` (any selector)                                    | `nodeRules` (selector specificity `≥ [0,0,1]` > `[0,0,0]`) |
+| `rules` vs `childNodeRules` (any selector)                               | `childNodeRules` (same reasoning)                          |
+| `nodeRules[0]` vs `nodeRules[1]` (same specificity)                      | `nodeRules[1]` (later in array)                            |
+| `nodeRules` (lower specificity) vs `childNodeRules` (higher specificity) | `childNodeRules` (higher specificity wins)                 |
+| `nodeRules` (higher specificity) vs `childNodeRules` (lower specificity) | `nodeRules` (higher specificity wins)                      |
+
+## Specificity
+
+### What is Specificity?
+
+Specificity is a three-element tuple `[a, b, c]` based on the CSS Selectors specification:
+
+| Component | Counts                                               | Examples                                            |
+| --------- | ---------------------------------------------------- | --------------------------------------------------- |
+| `a`       | ID selectors                                         | `#main` → `[1, 0, 0]`                               |
+| `b`       | Class selectors, attribute selectors, pseudo-classes | `.foo` → `[0, 1, 0]`, `[type="text"]` → `[0, 1, 0]` |
+| `c`       | Type selectors, pseudo-elements                      | `div` → `[0, 0, 1]`, `img` → `[0, 0, 1]`            |
+
+### How Specificity is Compared
+
+`compareSpecificity(a, b)` from `@markuplint/selector` performs a lexicographic comparison:
+
+```typescript
+function compareSpecificity(a: Specificity, b: Specificity): -1 | 0 | 1 {
+  // Compare a[0] vs b[0], then a[1] vs b[1], then a[2] vs b[2]
+  // Returns: -1 (a < b), 0 (equal), 1 (a > b)
+}
+```
+
+### How `RuleMapper.set()` Uses Specificity
+
+```typescript
+set(node, ruleName, rule: MappingLayer) {
+  const currentRule = rules[ruleName];
+  if (currentRule) {
+    const order = compareSpecificity(currentRule.specificity, rule.specificity);
+    if (order === 1) {
+      return;     // Current has higher specificity → skip new rule
+    }
+    // order === 0 or -1 → overwrite with new rule
+  }
+  rules[ruleName] = rule;
+}
+```
+
+- `order === 1` (current > new): **skip** — existing higher-specificity rule is preserved
+- `order === 0` (equal): **overwrite** — later mapping wins
+- `order === -1` (current < new): **overwrite** — higher-specificity rule wins
+
+### Specificity Examples
+
+```json
+{
+  "rules": {
+    "class-naming": "/^prefix-/"
+  },
+  "nodeRules": [
+    {
+      "selector": "div",
+      "rules": { "class-naming": "/^div-/" }
+    },
+    {
+      "selector": "div.special",
+      "rules": { "class-naming": "/^special-/" }
+    },
+    {
+      "selector": "#main",
+      "rules": { "class-naming": "/^main-/" }
+    }
+  ]
+}
+```
+
+For `<div id="main" class="special">`:
+
+| Source         | Selector      | Specificity | `class-naming` value |
+| -------------- | ------------- | ----------- | -------------------- |
+| `rules`        | (global)      | `[0, 0, 0]` | `/^prefix-/`         |
+| `nodeRules[0]` | `div`         | `[0, 0, 1]` | `/^div-/`            |
+| `nodeRules[1]` | `div.special` | `[0, 1, 1]` | `/^special-/`        |
+| `nodeRules[2]` | `#main`       | `[1, 0, 0]` | `/^main-/`           |
+
+Processing order: `rules` → `nodeRules[0]` → `nodeRules[1]` → `nodeRules[2]`
+
+Result: `class-naming` = `/^main-/` (specificity `[1, 0, 0]` is highest)
+
+## Merging with Global Rules
+
+When a `nodeRules` or `childNodeRules` entry specifies a rule, the value is **merged** with the global rule configuration rather than simply replacing it:
+
+```typescript
+const globalRule = ruleset.rules[ruleName];
+const mergedRule = globalRule == null ? convertedRule : mergeRule(globalRule, convertedRule);
+```
+
+`mergeRule(a, b)` (from `@markuplint/ml-config`) applies right-side precedence:
+
+| Scenario                 | Result                                                                                             |
+| ------------------------ | -------------------------------------------------------------------------------------------------- |
+| `b` is `false`           | Rule is disabled (returns `false`)                                                                 |
+| `b` is a primitive value | Replaces `a`'s value                                                                               |
+| Both are objects         | Properties from `b` override `a`; `severity`, `value`, `options`, `reason` are individually merged |
+| `b.options` exists       | Merged with `a.options` (objects are spread, arrays are concatenated)                              |
+| `b.value` is not set     | Inherits from `a.value`                                                                            |
+
+### Merging Example
+
+```json
+{
+  "rules": {
+    "my-rule": {
+      "severity": "error",
+      "value": "strict",
+      "options": { "allow": ["a", "b"] }
+    }
+  },
+  "nodeRules": [
+    {
+      "selector": "nav",
+      "rules": {
+        "my-rule": {
+          "options": { "allow": ["c"] }
+        }
+      }
+    }
+  ]
+}
+```
+
+For `<nav>`, `my-rule` is resolved as:
+
+```json
+{
+  "severity": "error",
+  "value": "strict",
+  "options": { "allow": ["c"] }
+}
+```
+
+`severity` and `value` are inherited from the global config. `options.allow` is overwritten by the `nodeRules` entry (object spread, not array concatenation at the `options` level — `options` itself is spread, not individual sub-properties).
+
+## Regex Selector and Template Variables
+
+`nodeRules` and `childNodeRules` support regex selectors, which can capture data from element attributes. Captured values are available as Mustache template variables in the rule configuration:
+
+```json
+{
+  "nodeRules": [
+    {
+      "regexSelector": {
+        "attrName": "data-prefix",
+        "attrValue": "/^(?<prefix>.+)$/"
+      },
+      "rules": {
+        "class-naming": "/^{{ prefix }}-/"
+      }
+    }
+  ]
+}
+```
+
+`exchangeValueOnRule(rule, matches.data)` renders these templates before merging.
+
+## Data Flow Diagram
+
+```
+Config
+  │
+  ▼
+Ruleset (rules, nodeRules, childNodeRules)
+  │
+  ▼
+_ruleMapping(ruleset)
+  │
+  ├─── Layer 1: Global rules
+  │    └─ For every node (including #document):
+  │         ruleMapper.set(node, name, { from: 'rules', specificity: [0,0,0], rule })
+  │
+  ├─── Layer 2: Node rules
+  │    └─ For each nodeRule entry:
+  │         └─ For each ELEMENT_NODE matching the selector:
+  │              ├─ exchangeValueOnRule (template rendering)
+  │              ├─ mergeRule (merge with global)
+  │              └─ ruleMapper.set(node, name, { from: 'nodeRules', specificity, rule })
+  │
+  └─── Layer 3: Child node rules
+       └─ For each childNodeRule entry:
+            └─ For each ELEMENT_NODE matching the selector:
+                 └─ For each child (or descendant if inheritance: true):
+                      ├─ exchangeValueOnRule (template rendering)
+                      ├─ mergeRule (merge with global)
+                      └─ ruleMapper.set(child, name, { from: 'childNodeRules', specificity, rule })
+  │
+  ▼
+ruleMapper.apply()
+  │
+  └─ For each node in the map:
+       node.rules[ruleName] = rule
+  │
+  ▼
+node.rules populated → ready for walkOn() verification
+```

package/docs/ml-dom.ja.md

@@ -0,0 +1,18 @@
+# MLDOM リファレンス
+
+`@markuplint/ml-core` の MLDOM サブシステムの詳細リファレンスです。
+
+## ドキュメント
+
+| ドキュメント                                       | 説明                                                                                       |
+| -------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| [概要](./ml-dom/overview.ja.md)                    | 概要、クラス階層、MLToken                                                                  |
+| [MLNode](./ml-dom/node.ja.md)                      | MLNode 抽象基底、MLParentNode                                                              |
+| [MLDocument](./ml-dom/document.ja.md)              | ドキュメントルートノード                                                                   |
+| [MLElement](./ml-dom/element.ja.md)                | 要素ノード（セレクタマッチング、属性、省略要素）                                           |
+| [Pretender システム](./ml-dom/pretender.ja.md)     | コンポーネントリンティング用の仮想要素マッピング（初期化、プロパティ委譲、アクセシブル名） |
+| [MLAttr](./ml-dom/attr.ja.md)                      | 属性ノード（トークン分解、スプレッド属性）                                                 |
+| [MLBlock](./ml-dom/block.ja.md)                    | プリプロセッサブロックノード（透過性、条件分岐子ノード、コンテンツモデル検証）             |
+| [ルールマッピング](./ml-dom/rule-mapping.ja.md)    | ルールがノードに適用される仕組み（3層処理、詳細度解決）                                    |
+| [その他のノード型](./ml-dom/others.ja.md)          | MLCharacterData, MLText, MLComment, MLDocumentType, MLElementCloseTag, MLDocumentFragment  |
+| [ヘルパーとユーティリティ](./ml-dom/helpers.ja.md) | ヘルパー関数、補助クラス、型ユーティリティ                                                 |

package/docs/ml-dom.md

@@ -0,0 +1,18 @@
+# MLDOM Reference
+
+Detailed reference for the MLDOM subsystem in `@markuplint/ml-core`.
+
+## Documents
+
+| Document                                   | Description                                                                                          |
+| ------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| [Overview](./ml-dom/overview.md)           | Overview, class hierarchy, MLToken                                                                   |
+| [MLNode](./ml-dom/node.md)                 | MLNode abstract base, MLParentNode                                                                   |
+| [MLDocument](./ml-dom/document.md)         | Document root node                                                                                   |
+| [MLElement](./ml-dom/element.md)           | Element node (selector matching, attributes, omitted elements)                                       |
+| [Pretender System](./ml-dom/pretender.md)  | Virtual element mapping for component linting (initialization, property delegation, accessible name) |
+| [MLAttr](./ml-dom/attr.md)                 | Attribute node (token decomposition, spread attributes)                                              |
+| [MLBlock](./ml-dom/block.md)               | Preprocessor block node (transparency, conditional child nodes, content model validation)            |
+| [Rule Mapping](./ml-dom/rule-mapping.md)   | How rules are applied to nodes (three-layer processing, specificity resolution)                      |
+| [Other Node Types](./ml-dom/others.md)     | MLCharacterData, MLText, MLComment, MLDocumentType, MLElementCloseTag, MLDocumentFragment            |
+| [Helpers & Utilities](./ml-dom/helpers.md) | Helper functions, supplementary classes, type utilities                                              |

package/docs/rule-system.ja.md

@@ -0,0 +1,270 @@
+# ルールシステム
+
+`@markuplint/ml-core` のルールフレームワークの詳細リファレンスです。
+
+## 概要
+
+ルールフレームワークはリントルールの完全なライフサイクルを処理します：定義、設定、ノードへのマッピング、実行、違反収集。主要コンポーネント：
+
+- **RuleSeed** — ルール定義型（verify/fix 関数 + デフォルト値）
+- **MLRule** — ルール実行クラス（シードを名前と設定解決でラップ）
+- **MLRuleContext** — ルールの実行コンテキスト（ドキュメントアクセス、翻訳、違反報告）
+- **RuleMapper** — セレクタ詳細度に基づいてルール設定を特定の DOM ノードにマッピング
+- **Ruleset** — Config から rules、nodeRules、childNodeRules を抽出
+
+## RuleSeed
+
+ソース: `src/ml-rule/types.ts`
+
+`RuleSeed<T, O>` 型はルールの実装を定義します。
+
+```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>;
+};
+```
+
+### カテゴリ値
+
+| カテゴリ              | 説明                                 |
+| --------------------- | ------------------------------------ |
+| `'validation'`        | HTML 標準準拠チェック                |
+| `'style'`             | コードスタイルとフォーマットのルール |
+| `'naming-convention'` | 命名規則の強制                       |
+| `'a11y'`              | アクセシビリティチェック             |
+| `'maintainability'`   | コード保守性のルール                 |
+
+### デフォルト値
+
+- `defaultSeverity` — 未指定の場合 `'error'`
+- `defaultValue` — 未指定の場合 `true`
+- `defaultOptions` — 未指定の場合 `undefined`
+
+## createRule
+
+ソース: `src/ml-rule/create-rule.ts`
+
+型安全なルールシード作成のためのファクトリ関数：
+
+```typescript
+function createRule<T extends RuleConfigValue, O extends PlainData = undefined>(
+  seed: Readonly<RuleSeed<T, O>>,
+): RuleSeed<T, O>;
+```
+
+シードをそのまま返します。主に TypeScript の型推論のためのヘルパーとして機能します。
+
+### 使用例
+
+```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 (/* 違反条件 */) {
+        report({ scope: el, message: t('エラーメッセージ') });
+      }
+    });
+  },
+});
+```
+
+## MLRule
+
+ソース: `src/ml-rule/ml-rule.ts`
+
+`MLRule<T, O>` は `RuleSeed` を名前でラップし、設定解決と検証実行を提供します。
+
+### コンストラクタ
+
+```typescript
+constructor(o: Readonly<RuleSeed<T, O>> & { readonly name: string })
+```
+
+### プロパティ
+
+| プロパティ        | 型         | 説明                                               |
+| ----------------- | ---------- | -------------------------------------------------- |
+| `name`            | `string`   | ルール識別子（例：`"attr-duplication"`）           |
+| `defaultSeverity` | `Severity` | デフォルトの重大度レベル（シードまたは `'error'`） |
+| `defaultValue`    | `T`        | デフォルト設定値（シードまたは `true`）            |
+| `defaultOptions`  | `O`        | デフォルトオプション（シードから）                 |
+
+### メソッド
+
+#### `verify(document, locale, fix): Promise<Violation[]>`
+
+ドキュメントに対してルールを実行します。
+
+**フロー:**
+
+1. `document.setRule(this)` — ドキュメントに現在のルールコンテキストを設定
+2. `new MLRuleContext(document, locale)` — 実行コンテキストを作成
+3. `context.provide()` — 提供可能なコンテキストオブジェクトを生成
+4. `await seed.verify(context)` — 検証を実行
+5. `await seed.fix(context)` — 修正を実行（`fix=true` かつ fix 関数がある場合）
+6. `context.reports` → `Violation[]` — レポートを違反にマッピング
+7. `document.setRule(null)` — ルールコンテキストをクリア
+
+**Report → Violation のマッピング:**
+
+- スコープベースのレポート: `report.scope`（ノード）から `line`, `col`, `raw` を抽出、重大度は `report.scope.rule.severity` から
+- 直接レポート: `report.line`, `report.col`, `report.raw` を直接使用、重大度は `document.rule.severity` から
+
+#### `getRuleInfo(ruleSet, ruleName): GlobalRuleInfo<T, O>`
+
+ルールセットから完全なルール情報を解決します。
+
+戻り値:
+
+```typescript
+{
+  ...RuleInfo<T, O>,               // グローバルルール設定
+  nodeRules: RuleInfo<T, O>[],     // 無効でないノードレベルのオーバーライド
+  childNodeRules: RuleInfo<T, O>[], // 無効でない子ノードレベルのオーバーライド
+}
+```
+
+#### `optimizeOption(configSettings): RuleInfo<T, O>`
+
+生のルール設定を解決済み `RuleInfo` に正規化します。
+
+| 入力                       | 結果                                                                                          |
+| -------------------------- | --------------------------------------------------------------------------------------------- |
+| `undefined` または `false` | `{ disabled: true, severity: デフォルト, value: デフォルト, options: デフォルト }`            |
+| `true`                     | `{ disabled: false, severity: デフォルト, value: デフォルト, options: デフォルト }`           |
+| `RuleConfig` オブジェクト  | `{ disabled: false, severity: 設定/デフォルト, value: 設定/デフォルト, options: マージ済み }` |
+| プリミティブ値             | `{ disabled: false, severity: デフォルト, value: 入力値, options: デフォルト }`               |
+
+オプションのマージ: 配列はスプレッド（`[...a, ...b]`）、オブジェクトはスプレッド（`{...a, ...b}`）、それ以外は `b ?? a` にフォールバック。
+
+## MLRuleContext
+
+ソース: `src/ml-rule/ml-rule-context.ts`
+
+`MLRuleContext<T, O>` はルールの実行コンテキストを提供します。
+
+### コンストラクタ
+
+```typescript
+constructor(document: MLDocument<T, O>, locale: LocaleSet)
+```
+
+ロケールから翻訳関数を作成し、ドキュメント参照を保存します。
+
+### プロパティ
+
+| プロパティ  | 型                 | 説明                    |
+| ----------- | ------------------ | ----------------------- |
+| `document`  | `MLDocument<T, O>` | 検証対象のドキュメント  |
+| `locale`    | `string`           | ロケール文字列          |
+| `translate` | `Translator`       | i18n メッセージ翻訳関数 |
+
+### `provide(): ProvidedContext`
+
+`RuleSeed.verify()` と `RuleSeed.fix()` に渡されるコンテキストオブジェクトを返します：
+
+```typescript
+{
+  document: MLDocument<T, O>,
+  translate: Translator,
+  t: Translator,        // translate のエイリアス
+  reports: Report<T, O>[],
+  report: (report) => void | boolean,
+}
+```
+
+### `report(report)`
+
+2 つのオーバーロード：
+
+1. **直接レポート**（`Report<T, O>`）: レポートを直接プッシュ。`undefined` を返す。
+2. **チェッカーレポート**（`CheckerReport<T, O>`）: 翻訳関数で関数を呼び出す。レポートが返された場合プッシュして `true` を返す。`null`/`undefined` の場合 `false` を返す。
+
+### 重複排除
+
+レポートは `_push()` で以下の基準で重複排除されます：
+
+- **スコープベース**: 同じ `scope` オブジェクト + 同じ `message`
+- **位置ベース**: 同じ `col` + `line` + `message` + `raw`
+
+### メッセージの最終処理
+
+英語ロケール（`'en'`）の場合、最初の小文字が大文字に変換されます。他のロケールはそのまま通過します。
+
+## チェッカー型
+
+ソース: `src/ml-rule/types.ts`
+
+チェッカー関数を構築するためのユーティリティ型：
+
+| 型                        | シグネチャ                                                   | 説明               |
+| ------------------------- | ------------------------------------------------------------ | ------------------ |
+| `Checker<T, O, P>`        | `(params: P) => CheckerReport<T, O>`                         | 汎用チェッカー     |
+| `ElementChecker<T, O, P>` | `(params: P & { el: Element<T, O> }) => CheckerReport<T, O>` | 要素固有チェッカー |
+| `AttrChecker<T, O, P>`    | `(params: P & { attr: Attr<T, O> }) => CheckerReport<T, O>`  | 属性固有チェッカー |
+| `CheckerReport<T, O>`     | `(t: Translator) => Report<T, O> \| undefined \| null`       | 遅延レポート関数   |
+
+## ルールマッピング
+
+`RuleMapper`、ルール設定の解決（`rules`、`nodeRules`、`childNodeRules` の3層処理）、詳細度ベースの競合解決、マージ動作、正規表現セレクタのテンプレート変数についての詳細なドキュメントは、専用の[ルールマッピング](./ml-dom/rule-mapping.ja.md)リファレンスを参照してください。
+
+## Ruleset
+
+ソース: `src/ruleset/index.ts`
+
+`Config` オブジェクトからルール設定を抽出します。
+
+```typescript
+class Ruleset {
+  readonly rules: Rules;
+  readonly nodeRules: readonly NodeRule[];
+  readonly childNodeRules: readonly ChildNodeRule[];
+
+  constructor(config: Config);
+}
+```
+
+- `rules` — グローバルルール定義（`config.rules` から、デフォルトは `{}`）
+- `nodeRules` — ノード固有のオーバーライド（`config.nodeRules` から、デフォルトは `[]`）
+- `childNodeRules` — 子ノード固有のオーバーライド（`config.childNodeRules` から、デフォルトは `[]`）
+
+## テストユーティリティ
+
+ソース: `src/ml-rule/create-test-rule.ts`
+
+### createTestRule
+
+```typescript
+function createRule<T, O>(seed: Readonly<RuleSeed<T, O>> & { readonly name: string }): MLRule<T, O>;
+```
+
+テスト用の `MLRule` インスタンスを作成します。`create-rule.ts` の `createRule()` とは異なり、`name` プロパティが必須で、実際の `MLRule` インスタンスを返します。
+
+### テストパターン
+
+```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 }) {
+    // 検証ロジック
+  },
+});
+
+const doc = createTestDocument('<div></div>');
+const violations = await rule.verify(doc, { locale: 'en' }, false);
+```