@markuplint/ml-config 4.8.14 → 5.0.0-alpha.0

package/ARCHITECTURE.ja.md

@@ -0,0 +1,314 @@
+# @markuplint/ml-config
+
+## 概要
+
+`@markuplint/ml-config` は markuplint の設定システムの中核パッケージです。`Config` 型階層、複数の設定レイヤー（ベース、extends、overrides）を一つの最適化された設定にマージするアルゴリズム、キャプチャ変数をルール設定に注入する Mustache テンプレートレンダリングシステムを提供します。`@markuplint/file-resolver`（設定ファイルの読み込みと解決）と `@markuplint/ml-core`（マージ済み設定を使用してルールを適用）の間に位置します。
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts              — すべての公開 API を再エクスポート
+├── types.ts              — 全型定義（Config, Rule, Pretender, Violation 等）
+├── merge-config.ts       — マージアルゴリズム（mergeConfig, mergeRule, ヘルパー関数）
+├── merge-config.spec.ts  — マージアルゴリズムのテスト
+├── utils.ts              — テンプレートレンダリング、ルール正規化、型ガード
+└── utils.spec.ts         — ユーティリティのテスト
+```
+
+## 型システム
+
+### Config 型階層
+
+```mermaid
+classDiagram
+    class Config {
+        +$schema?: string
+        +extends?: string | string[]
+        +plugins?: (PluginConfig | string)[]
+        +parser?: ParserConfig
+        +parserOptions?: ParserOptions
+        +specs?: SpecConfig
+        +excludeFiles?: string[]
+        +severity?: SeverityOptions
+        +pretenders?: Pretender[] | PretenderDetails
+        +rules?: Rules
+        +nodeRules?: NodeRule[]
+        +childNodeRules?: ChildNodeRule[]
+        +overrideMode?: "merge" | "reset"
+        +overrides?: Record~string, OverrideConfig~
+    }
+
+    class OverrideConfig {
+        <<Omit Config NoInherit>>
+    }
+
+    class OptimizedConfig {
+        +plugins?: PluginConfig[]
+        +pretenders?: PretenderDetails
+        +overrides?: Record~string, OptimizedOverrideConfig~
+    }
+
+    Config --> OverrideConfig : "Omit $schema, extends,\noverrideMode, overrides"
+    Config --> OptimizedConfig : "mergeConfig()"
+    OverrideConfig --> OptimizedOverrideConfig : "mergeConfig()"
+```
+
+### Config から OptimizedConfig への変換
+
+| フィールド   | Config                            | OptimizedConfig                           | 変換                                   |
+| ------------ | --------------------------------- | ----------------------------------------- | -------------------------------------- |
+| `plugins`    | `(PluginConfig \| string)[]`      | `PluginConfig[]`                          | 文字列を `{name}` オブジェクトに正規化 |
+| `pretenders` | `Pretender[] \| PretenderDetails` | `PretenderDetails`                        | 配列を `{data: [...]}` に変換          |
+| `extends`    | `string \| string[]`              | 削除                                      | マージ後は不要                         |
+| `$schema`    | `string`                          | 削除                                      | メタデータのみ                         |
+| `overrides`  | `Record<string, OverrideConfig>`  | `Record<string, OptimizedOverrideConfig>` | 各値を再帰的にマージ                   |
+
+### ルール型の3形式
+
+ルールは3つの形式で設定できます:
+
+| 形式    | 型                | 例                                   | 意味                        |
+| ------- | ----------------- | ------------------------------------ | --------------------------- |
+| Boolean | `boolean`         | `true` / `false`                     | デフォルトで有効化 / 無効化 |
+| Value   | `RuleConfigValue` | `"always"`, `["a","b"]`, `null`      | ショートハンド値            |
+| Object  | `RuleConfig<T,O>` | `{severity, value, options, reason}` | フル設定                    |
+
+```ts
+type Rule<T, O> = RuleConfig<T, O> | Readonly<T> | boolean;
+
+type RuleConfig<T, O> = {
+  severity?: Severity; // 'error' | 'warning' | 'info'
+  value?: Readonly<T>;
+  options?: Readonly<O>;
+  reason?: string;
+};
+```
+
+### NodeRule / ChildNodeRule
+
+- `NodeRule` -- CSS セレクタ、正規表現セレクタ、ARIA ロール、カテゴリ、obsolete フラグで対象ノードを限定し、ルール設定をオーバーライド。オプションの `name`（`/` を含む必要あり）で named nodeRule として仮想ルールに展開可能。オプションの `specConformance`（`'normative'` または `'non-normative'`）を下流ツールやレポート向けのメタデータとして設定
+- `ChildNodeRule` -- `NodeRule` と類似だが子ノードを対象とする。`inheritance` フラグで子孫への継承を制御。`name` と `specConformance`（メタデータ）による named nodeRule 展開もサポート
+
+### Pretender 型
+
+- `Pretender` -- CSS セレクタを使用してカスタム要素を標準要素に見せかける。`as` フィールドで要素名または詳細な `OriginalNode` を指定
+- `OriginalNode` -- 要素名、スロット、名前空間、属性、継承属性、ARIA プロパティを定義
+- `PretenderDetails` -- マージ後に使用される正規化形式 `{data?, files?, imports?}`
+
+## マージアルゴリズム
+
+このパッケージの中核です。`mergeConfig()` 関数はプロパティごとの戦略で2つの設定を統合します。
+
+### mergeConfig() の全体フロー
+
+```ts
+mergeConfig(a: Config, b?: Config): OptimizedConfig
+```
+
+```mermaid
+flowchart TD
+    A["入力: ベース (a) + オーバーライド (b)"] --> B{"b が指定されている?"}
+    B -->|Yes| C["deleteExtendsProp = true"]
+    B -->|No| C2["b = {}, deleteExtendsProp = false"]
+    C --> D["スプレッド: {...a, ...b}\n(プリミティブフィールドは右辺優先)"]
+    C2 --> D
+    D --> E["プロパティ別マージ戦略を適用\n(下記テーブル参照)"]
+    E --> F{"deleteExtendsProp?"}
+    F -->|Yes| G["結果から extends を削除"]
+    F -->|No| H["extends を保持"]
+    G --> I["deleteUndefProp()\nundefined プロパティを除去"]
+    H --> I
+    I --> J["OptimizedConfig を返却"]
+```
+
+### プロパティ別マージ戦略テーブル
+
+| プロパティ       | 戦略                       | ヘルパー関数                                         | 詳細                                          |
+| ---------------- | -------------------------- | ---------------------------------------------------- | --------------------------------------------- |
+| `plugins`        | 結合+重複排除+正規化       | `concatArray(uniquely=true, comparePropName='name')` | 同名プラグインは settings を shallow merge    |
+| `parser`         | オブジェクト shallow merge | `mergeObject()`                                      | `{...a, ...b}` で右辺優先                     |
+| `parserOptions`  | オブジェクト shallow merge | `mergeObject()`                                      | 同上                                          |
+| `specs`          | オブジェクト shallow merge | `mergeObject()`                                      | 同上                                          |
+| `excludeFiles`   | 結合+重複排除              | `concatArray(uniquely=true)`                         | 単純な値の重複排除                            |
+| `severity`       | オブジェクト shallow merge | `mergeObject()`                                      | parser と同様                                 |
+| `pretenders`     | セマンティックマージ       | `mergePretenders()`                                  | files/imports: 上書き、data: 追加             |
+| `rules`          | ルール別マージ             | `mergeRules()` → `mergeRule()`                       | **最も複雑 -- 次節で詳述**                    |
+| `nodeRules`      | 結合+名前で重複排除        | `concatArray(uniquely=true, comparePropName='name')` | 名前付きエントリは重複排除、無名は追加        |
+| `childNodeRules` | 結合+名前で重複排除        | `concatArray(uniquely=true, comparePropName='name')` | nodeRules と同様                              |
+| `overrideMode`   | 右辺優先                   | `b.overrideMode ?? a.overrideMode`                   | 単純な優先順位                                |
+| `overrides`      | キー別再帰マージ           | `mergeOverrides()`                                   | 各キーに対して `mergeConfig()` を再帰呼び出し |
+| `extends`        | 結合→削除                  | `concatArray()`                                      | マージ後に結果から削除                        |
+
+### mergeRule() -- ルールマージの詳細
+
+```ts
+mergeRule(a: Nullable<AnyRule>, b: AnyRule): AnyRule
+```
+
+最も複雑なマージロジックを処理する関数です。両方の入力はまず `optimizeRule()` で正規化されます。
+
+```mermaid
+flowchart TD
+    Start["mergeRule(a, b)"] --> OptAB["optimizeRule() で両方を正規化"]
+    OptAB --> ChkFalse{"b === false OR\nb.value === false?"}
+    ChkFalse -->|Yes| RetFalse["return false\n(絶対無効化)"]
+    ChkFalse -->|No| ChkAUndef{"a === undefined?"}
+    ChkAUndef -->|Yes| RetB["return b"]
+    ChkAUndef -->|No| ChkBUndef{"b === undefined?"}
+    ChkBUndef -->|Yes| RetA["return a"]
+    ChkBUndef -->|No| ChkBVal{"b は Value?\n(primitive/null/array)"}
+    ChkBVal -->|Yes| ChkAVal{"a は Value?"}
+    ChkAVal -->|Yes| RetBVal["return b\n(右辺優先、\n配列も上書き)"]
+    ChkAVal -->|No| MergeValObj["a の severity/reason を保持\nvalue を b で上書き"]
+    ChkBVal -->|No| MergeObj["severity: b ?? a\nvalue: b ?? a\noptions: mergeObject(a, b)\nreason: b ?? a"]
+```
+
+**重要な設計判断:**
+
+1. **`false` は絶対無効化** -- override が `false`（または `{value: false}`）なら、base が何であっても結果は常に `false`
+2. **配列値は上書き** -- `["a","b"]` + `["c","d"]` は `["c","d"]` になる（右辺優先）。ESLint や Biome と一貫した動作
+3. **options は shallow merge** -- severity、value、reason は右辺優先だが、options のみ `mergeObject()`（`{...a, ...b}` による shallow merge）を使用
+
+### ヘルパー関数
+
+#### concatArray(a, b, uniquely?, comparePropName?)
+
+オプションの重複排除付きで2つの配列を連結:
+
+- `uniquely=false` -- 単純な連結、重複排除なし
+- `uniquely=true`、`comparePropName` なし -- 完全一致で重複排除
+- `uniquely=true`、`comparePropName` あり -- 指定プロパティ名で重複排除。同名オブジェクトはオブジェクトスプレッドで shallow merge（例: プラグインの settings）
+- 空の結果には `undefined` を返す
+
+#### mergeObject(a, b)
+
+`{...a, ...b}` による shallow merge。トップレベルで右辺の値が優先。結果から undefined プロパティを除去。
+
+#### mergeOverrides(a, b)
+
+両方の override レコードから全キーの集合を取得。各キーに対して `mergeConfig(a[key], b[key])` を再帰呼び出し。各結果から `$schema`、`extends`、`overrides` を削除（これらはトップレベル専用プロパティ）。
+
+#### mergePretenders(a, b)
+
+配列形式の pretenders を正規化形式 `PretenderDetails`（`{data: [...]}`）に変換してからセマンティックマージ: `files`/`imports` は上書き（右辺優先）、`data` は追加（連結）。
+
+## テンプレートレンダリングシステム
+
+### provideValue(template, data)
+
+Mustache テンプレート文字列を提供されたデータでレンダリング:
+
+- テンプレートに変数がない -- テンプレートをそのまま返す
+- 変数があるが data にマッチするキーがない -- `undefined` を返す
+- 変数があり data にマッチするキーがある -- レンダリング結果を返す
+
+### exchangeValueOnRule(rule, data)
+
+ルール設定内のすべての文字列値に Mustache テンプレートレンダリングを適用:
+
+- **value** -- 文字列値はレンダリングされる。配列の各要素も個別にレンダリング
+- **options** -- options オブジェクト内のすべての文字列値を再帰的にレンダリング
+- **reason** -- 文字列としてレンダリング
+
+この関数は `nodeRules` / `childNodeRules` の `regexSelector` で使用され、キャプチャグループ（`$0`、`$1`、`dataName` 等の名前付きキャプチャ）がテンプレート変数としてルール設定に注入されます。
+
+## ユーティリティ関数
+
+| 関数                  | 目的                                                                                              |
+| --------------------- | ------------------------------------------------------------------------------------------------- |
+| `cleanOptions()`      | 標準フィールド（`severity`、`value`、`options`、`reason`）を抽出して undefined プロパティを除去   |
+| `isRuleConfigValue()` | 型ガード: プリミティブ、`null`、配列（= `RuleConfig` オブジェクトではない）に対して `true` を返す |
+| `deleteUndefProp()`   | プレーンオブジェクトから `undefined` 値のプロパティをすべて in-place で削除                       |
+
+## 主要ソースファイル
+
+| ファイル              | 目的                                                                                                    |
+| --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `src/types.ts`        | 全型定義（Config, Rule, Pretender, Violation 等）                                                       |
+| `src/merge-config.ts` | `mergeConfig()`、`mergeRule()`、全ヘルパー関数                                                          |
+| `src/utils.ts`        | `provideValue()`、`exchangeValueOnRule()`、`cleanOptions()`、`isRuleConfigValue()`、`deleteUndefProp()` |
+| `src/index.ts`        | 全公開 API の再エクスポート                                                                             |
+
+## 外部依存関係
+
+| 依存パッケージ         | 用途                                                |
+| ---------------------- | --------------------------------------------------- |
+| `@markuplint/ml-ast`   | `ParserOptions` 型（型のみ）                        |
+| `@markuplint/selector` | `RegexSelector` 型（再エクスポート）                |
+| `@markuplint/shared`   | `Nullable` ユーティリティ型                         |
+| `is-plain-object`      | `deleteUndefProp()` でのプレーンオブジェクト判定    |
+| `mustache`             | `provideValue()` のテンプレートレンダリングエンジン |
+| `type-fest`            | `Writable` ユーティリティ型                         |
+
+## 統合ポイント
+
+```mermaid
+flowchart LR
+    subgraph upstream ["上流"]
+        fileResolver["@markuplint/file-resolver\n(設定ファイル読み込み,\nextends チェーン解決)"]
+    end
+
+    subgraph pkg ["@markuplint/ml-config"]
+        mergeConfig["mergeConfig()\n(マージアルゴリズム)"]
+        types["Config 型定義"]
+        templates["テンプレートレンダリング"]
+    end
+
+    subgraph downstream ["下流"]
+        mlCore["@markuplint/ml-core\n(OptimizedConfig を使用して\nルールを適用)"]
+        rules["@markuplint/rules\n(Rule<T,O>,\nRuleConfig<T,O> 型を使用)"]
+    end
+
+    fileResolver -->|"各 extends レイヤーで\nmergeConfig() を呼び出し"| mergeConfig
+    mergeConfig -->|"OptimizedConfig を生成"| mlCore
+    types -->|"Rule, RuleConfig 型"| rules
+```
+
+### 上流
+
+- **`@markuplint/file-resolver`** -- 設定ファイルを読み込み、extends チェーンを解決し、`mergeConfig()` を呼び出してレイヤーを統合
+
+### 下流
+
+- **`@markuplint/ml-core`** -- マージ済みの `OptimizedConfig` を受け取り、パース済みドキュメントにルールを適用
+- **`@markuplint/rules`** -- `Rule<T,O>` と `RuleConfig<T,O>` 型を使用してルール実装を定義
+
+## 設計判断
+
+### Flat Config を採用しない理由
+
+ESLint の Flat Config アプローチを評価した結果、markuplint には不適と判断しました:
+
+- **ESLint 自体が 2025年3月に Flat Config へ `extends` を再追加** -- 純粋な Flat アプローチは JavaScript ツールでも不十分だった
+- **markuplint は JSON ベース** -- Flat Config は JavaScript を前提とする。HTML/マークアップ開発者（主要ユーザー層）にとって、JSON のスキーマ検証と言語非依存性は大きなメリット
+- **markuplint の `nodeRules`/`childNodeRules` は CSS セレクタベース** -- Flat Config のファイルパターンモデルに対応する仕組みがない
+- **ESLint v9 への移行はコミュニティに大きな痛みを与えた** -- 段階的な移行には自動化ツールと数年のエコシステム適応が必要だった
+
+**結論:** JSON ベースの `extends` マージ戦略の改善が markuplint にとって最適なアプローチ。
+
+### マージ戦略の原則
+
+配列の扱いには論理的な区別があります:
+
+| 配列の種類                     | 例                                     | マージ動作 | 根拠                   |
+| ------------------------------ | -------------------------------------- | ---------- | ---------------------- |
+| **トップレベルのコレクション** | `plugins`, `excludeFiles`, `nodeRules` | 累積       | 独立したアイテムの集合 |
+| **ルール値**                   | `["allowed-tag-1", "allowed-tag-2"]`   | 上書き     | 1つのルールの設定値    |
+
+これは ESLint と Biome の動作と一貫しており、ルール値はより具体的な設定で常に上書きされます。
+
+### Deep Merge ではなく Shallow Merge
+
+| ツール     | ルール options のマージ       | 根拠                                                                       |
+| ---------- | ----------------------------- | -------------------------------------------------------------------------- |
+| ESLint     | 完全リプレース                | 最もシンプルだが驚きがある                                                 |
+| Biome      | Deep merge（Merge trait経由） | 完全な柔軟性、高い複雑性                                                   |
+| markuplint | **Shallow merge**             | 中間地点: トップレベルのキーはマージ、ネストされたオブジェクトはリプレース |
+
+`deepmerge` ライブラリを削除し、シンプルなオブジェクトスプレッド（`{...a, ...b}`）に置き換えました。markuplint の設定でマージされるすべてのオブジェクト（parser、specs、parserOptions、severity、プラグイン設定、ルールオプション）はフラットなキーバリューマップであるため、これで十分です。
+
+## ドキュメントマップ
+
+- [マイグレーションガイド](../../docs/migration/v4-v5/config.ja.md) -- メジャーバージョン間の破壊的変更
+- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、レシピ、トラブルシューティング

package/ARCHITECTURE.md

@@ -0,0 +1,314 @@
+# @markuplint/ml-config
+
+## Overview
+
+`@markuplint/ml-config` is the configuration system core for markuplint. It provides the `Config` type hierarchy, the merge algorithm that combines multiple configuration layers (base, extends, overrides) into a single optimized config, and a Mustache template rendering system for injecting captured variables into rule settings. The package sits between `@markuplint/file-resolver` (which reads and resolves config files) and `@markuplint/ml-core` (which applies rules using the merged config).
+
+## Directory Structure
+
+```
+src/
+├── index.ts              — Re-exports all public APIs
+├── types.ts              — All type definitions (Config, Rule, Pretender, Violation, etc.)
+├── merge-config.ts       — Merge algorithm (mergeConfig, mergeRule, helpers)
+├── merge-config.spec.ts  — Merge algorithm tests
+├── utils.ts              — Template rendering, rule normalization, type guards
+└── utils.spec.ts         — Utils tests
+```
+
+## Type System
+
+### Config Type Hierarchy
+
+```mermaid
+classDiagram
+    class Config {
+        +$schema?: string
+        +extends?: string | string[]
+        +plugins?: (PluginConfig | string)[]
+        +parser?: ParserConfig
+        +parserOptions?: ParserOptions
+        +specs?: SpecConfig
+        +excludeFiles?: string[]
+        +severity?: SeverityOptions
+        +pretenders?: Pretender[] | PretenderDetails
+        +rules?: Rules
+        +nodeRules?: NodeRule[]
+        +childNodeRules?: ChildNodeRule[]
+        +overrideMode?: "merge" | "reset"
+        +overrides?: Record~string, OverrideConfig~
+    }
+
+    class OverrideConfig {
+        <<Omit Config NoInherit>>
+    }
+
+    class OptimizedConfig {
+        +plugins?: PluginConfig[]
+        +pretenders?: PretenderDetails
+        +overrides?: Record~string, OptimizedOverrideConfig~
+    }
+
+    Config --> OverrideConfig : "Omit $schema, extends,\noverrideMode, overrides"
+    Config --> OptimizedConfig : "mergeConfig()"
+    OverrideConfig --> OptimizedOverrideConfig : "mergeConfig()"
+```
+
+### Config to OptimizedConfig Conversion
+
+| Field        | Config                            | OptimizedConfig                           | Conversion                             |
+| ------------ | --------------------------------- | ----------------------------------------- | -------------------------------------- |
+| `plugins`    | `(PluginConfig \| string)[]`      | `PluginConfig[]`                          | Strings normalized to `{name}` objects |
+| `pretenders` | `Pretender[] \| PretenderDetails` | `PretenderDetails`                        | Arrays converted to `{data: [...]}`    |
+| `extends`    | `string \| string[]`              | Removed                                   | No longer needed after merging         |
+| `$schema`    | `string`                          | Removed                                   | Metadata only                          |
+| `overrides`  | `Record<string, OverrideConfig>`  | `Record<string, OptimizedOverrideConfig>` | Each value recursively merged          |
+
+### Rule Type Forms
+
+A rule can be configured in three forms:
+
+| Form    | Type              | Example                              | Meaning                        |
+| ------- | ----------------- | ------------------------------------ | ------------------------------ |
+| Boolean | `boolean`         | `true` / `false`                     | Enable with defaults / disable |
+| Value   | `RuleConfigValue` | `"always"`, `["a","b"]`, `null`      | Shorthand value                |
+| Object  | `RuleConfig<T,O>` | `{severity, value, options, reason}` | Full configuration             |
+
+```ts
+type Rule<T, O> = RuleConfig<T, O> | Readonly<T> | boolean;
+
+type RuleConfig<T, O> = {
+  severity?: Severity; // 'error' | 'warning' | 'info'
+  value?: Readonly<T>;
+  options?: Readonly<O>;
+  reason?: string;
+};
+```
+
+### NodeRule / ChildNodeRule
+
+- `NodeRule` -- Targets specific nodes by CSS selector, regex selector, ARIA roles, categories, or obsolete flag, then overrides their rule settings. Supports an optional `name` (must contain `/`) for named nodeRule expansion into virtual rules, and an optional `specConformance` (`'normative'` or `'non-normative'`) as metadata for downstream tools and reporting
+- `ChildNodeRule` -- Similar to `NodeRule` but targets child nodes; includes an `inheritance` flag to control whether overrides propagate to descendants. Also supports `name` and `specConformance` (metadata) for named nodeRule expansion
+
+### Pretender Types
+
+- `Pretender` -- Uses a CSS selector to make custom elements appear as standard elements for linting purposes; the `as` field specifies the element name or a detailed `OriginalNode`
+- `OriginalNode` -- Defines an element's name, slots, namespace, attributes, inherited attributes, and ARIA properties
+- `PretenderDetails` -- Normalized form `{data?, files?, imports?}` used after merging
+
+## Merge Algorithm
+
+This is the core of the package. The `mergeConfig()` function combines two configurations with property-specific strategies.
+
+### mergeConfig() Overall Flow
+
+```ts
+mergeConfig(a: Config, b?: Config): OptimizedConfig
+```
+
+```mermaid
+flowchart TD
+    A["Input: base (a) + override (b)"] --> B{"b provided?"}
+    B -->|Yes| C["Set deleteExtendsProp = true"]
+    B -->|No| C2["Set b = {}, deleteExtendsProp = false"]
+    C --> D["Spread: {...a, ...b}\n(primitive fields: right-side wins)"]
+    C2 --> D
+    D --> E["Apply per-property\nmerge strategies\n(see table below)"]
+    E --> F{"deleteExtendsProp?"}
+    F -->|Yes| G["Delete extends from result"]
+    F -->|No| H["Keep extends"]
+    G --> I["deleteUndefProp()\nRemove undefined properties"]
+    H --> I
+    I --> J["Return OptimizedConfig"]
+```
+
+### Per-Property Merge Strategy Table
+
+| Property         | Strategy                         | Helper Function                                      | Details                                              |
+| ---------------- | -------------------------------- | ---------------------------------------------------- | ---------------------------------------------------- |
+| `plugins`        | Concat + deduplicate + normalize | `concatArray(uniquely=true, comparePropName='name')` | Same-name plugins have their settings shallow-merged |
+| `parser`         | Object shallow merge             | `mergeObject()`                                      | Right-side wins via `{...a, ...b}`                   |
+| `parserOptions`  | Object shallow merge             | `mergeObject()`                                      | Same as above                                        |
+| `specs`          | Object shallow merge             | `mergeObject()`                                      | Same as above                                        |
+| `excludeFiles`   | Concat + deduplicate             | `concatArray(uniquely=true)`                         | Simple value deduplication                           |
+| `severity`       | Object shallow merge             | `mergeObject()`                                      | Same as parser                                       |
+| `pretenders`     | Semantic merge                   | `mergePretenders()`                                  | files/imports: override, data: append                |
+| `rules`          | Per-rule merge                   | `mergeRules()` then `mergeRule()`                    | **Most complex -- see next section**                 |
+| `nodeRules`      | Concat + deduplicate by name     | `concatArray(uniquely=true, comparePropName='name')` | Named entries deduplicated; unnamed entries appended |
+| `childNodeRules` | Concat + deduplicate by name     | `concatArray(uniquely=true, comparePropName='name')` | Same as nodeRules                                    |
+| `overrideMode`   | Right-side wins                  | `b.overrideMode ?? a.overrideMode`                   | Simple precedence                                    |
+| `overrides`      | Per-key recursive merge          | `mergeOverrides()`                                   | Calls `mergeConfig()` recursively for each key       |
+| `extends`        | Concat then delete               | `concatArray()`                                      | Removed from result after merge                      |
+
+### mergeRule() -- Rule Merge Details
+
+```ts
+mergeRule(a: Nullable<AnyRule>, b: AnyRule): AnyRule
+```
+
+This function handles the most complex merge logic. Both inputs are first normalized via `optimizeRule()`.
+
+```mermaid
+flowchart TD
+    Start["mergeRule(a, b)"] --> OptAB["Normalize both via optimizeRule()"]
+    OptAB --> ChkFalse{"b === false OR\nb.value === false?"}
+    ChkFalse -->|Yes| RetFalse["return false\n(absolute disable)"]
+    ChkFalse -->|No| ChkAUndef{"a === undefined?"}
+    ChkAUndef -->|Yes| RetB["return b"]
+    ChkAUndef -->|No| ChkBUndef{"b === undefined?"}
+    ChkBUndef -->|Yes| RetA["return a"]
+    ChkBUndef -->|No| ChkBVal{"b is Value?\n(primitive/null/array)"}
+    ChkBVal -->|Yes| ChkAVal{"a is Value?"}
+    ChkAVal -->|Yes| RetBVal["return b\n(right-side wins,\narrays override)"]
+    ChkAVal -->|No| MergeValObj["Keep a's severity/reason\nOverride value with b"]
+    ChkBVal -->|No| MergeObj["severity: b ?? a\nvalue: b ?? a\noptions: mergeObject(a, b)\nreason: b ?? a"]
+```
+
+**Key Design Decisions:**
+
+1. **`false` is absolute disable** -- If the override is `false` (or `{value: false}`), the result is always `false`, regardless of what the base config says
+2. **Array values override** -- `["a","b"]` + `["c","d"]` results in `["c","d"]` (right-side wins), consistent with ESLint and Biome behavior
+3. **options uses shallow merge** -- While severity, value, and reason use right-side-wins precedence, options uses `mergeObject()` (shallow merge via `{...a, ...b}`)
+
+### Helper Functions
+
+#### concatArray(a, b, uniquely?, comparePropName?)
+
+Concatenates two arrays with optional deduplication:
+
+- `uniquely=false` -- Simple concatenation, no deduplication
+- `uniquely=true`, no `comparePropName` -- Exact-match deduplication
+- `uniquely=true`, with `comparePropName` -- Deduplicates by the specified property name; when two objects share the same name, they are shallow-merged via object spread (e.g., plugin settings)
+- Returns `undefined` for empty results
+
+#### mergeObject(a, b)
+
+Shallow merges two objects via `{...a, ...b}`. Right-side values take precedence at the top level. Removes undefined properties from the result.
+
+#### mergeOverrides(a, b)
+
+Collects the union of all keys from both override records. For each key, calls `mergeConfig(a[key], b[key])` recursively. Removes `$schema`, `extends`, and `overrides` from each result (since these are top-level-only properties).
+
+#### mergePretenders(a, b)
+
+Converts array-form pretenders to the normalized `PretenderDetails` form (`{data: [...]}`) then applies semantic merge: `files`/`imports` are overridden (right-side wins), `data` is appended (concatenated).
+
+## Template Rendering System
+
+### provideValue(template, data)
+
+Renders a Mustache template string with the provided data:
+
+- No variables in template -- Returns the template unchanged
+- Variables present but no matching keys in data -- Returns `undefined`
+- Variables present with matching keys -- Returns the rendered result
+
+### exchangeValueOnRule(rule, data)
+
+Applies Mustache template rendering to all string values within a rule configuration:
+
+- **value** -- String values are rendered; array elements are individually rendered
+- **options** -- Recursively renders all string values in the options object
+- **reason** -- Rendered as a string
+
+This function is used by `nodeRules` and `childNodeRules` with `regexSelector`, where captured groups (`$0`, `$1`, named captures like `dataName`) are injected as template variables into rule settings.
+
+## Utility Functions
+
+| Function              | Purpose                                                                                           |
+| --------------------- | ------------------------------------------------------------------------------------------------- |
+| `cleanOptions()`      | Extracts standard fields (`severity`, `value`, `options`, `reason`), removes undefined properties |
+| `isRuleConfigValue()` | Type guard: returns `true` for primitives, `null`, and arrays (i.e., not a `RuleConfig` object)   |
+| `deleteUndefProp()`   | Removes all properties with `undefined` values from a plain object in-place                       |
+
+## Key Source Files
+
+| File                  | Purpose                                                                                                 |
+| --------------------- | ------------------------------------------------------------------------------------------------------- |
+| `src/types.ts`        | All type definitions (Config, Rule, Pretender, Violation, etc.)                                         |
+| `src/merge-config.ts` | `mergeConfig()`, `mergeRule()`, and all helper functions                                                |
+| `src/utils.ts`        | `provideValue()`, `exchangeValueOnRule()`, `cleanOptions()`, `isRuleConfigValue()`, `deleteUndefProp()` |
+| `src/index.ts`        | Re-exports all public APIs                                                                              |
+
+## External Dependencies
+
+| Dependency             | Purpose                                        |
+| ---------------------- | ---------------------------------------------- |
+| `@markuplint/ml-ast`   | `ParserOptions` type (type-only)               |
+| `@markuplint/selector` | `RegexSelector` type (re-exported)             |
+| `@markuplint/shared`   | `Nullable` utility type                        |
+| `is-plain-object`      | Plain object detection in `deleteUndefProp()`  |
+| `mustache`             | Template rendering engine for `provideValue()` |
+| `type-fest`            | `Writable` utility type                        |
+
+## Integration Points
+
+```mermaid
+flowchart LR
+    subgraph upstream ["Upstream"]
+        fileResolver["@markuplint/file-resolver\n(reads config files,\nresolves extends chain)"]
+    end
+
+    subgraph pkg ["@markuplint/ml-config"]
+        mergeConfig["mergeConfig()\n(merge algorithm)"]
+        types["Config types"]
+        templates["Template rendering"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core\n(applies rules using\nOptimizedConfig)"]
+        rules["@markuplint/rules\n(uses Rule<T,O>,\nRuleConfig<T,O> types)"]
+    end
+
+    fileResolver -->|"calls mergeConfig()\nfor each extends layer"| mergeConfig
+    mergeConfig -->|"produces OptimizedConfig"| mlCore
+    types -->|"Rule, RuleConfig types"| rules
+```
+
+### Upstream
+
+- **`@markuplint/file-resolver`** -- Reads configuration files, resolves the extends chain, and calls `mergeConfig()` to combine layers
+
+### Downstream
+
+- **`@markuplint/ml-core`** -- Receives the merged `OptimizedConfig` and applies rules to the parsed document
+- **`@markuplint/rules`** -- Uses `Rule<T,O>` and `RuleConfig<T,O>` types to define rule implementations
+
+## Design Decisions
+
+### Why Not Flat Config?
+
+ESLint's Flat Config approach was evaluated and rejected for markuplint:
+
+- **ESLint itself re-added `extends` to Flat Config in March 2025** -- The pure flat approach proved insufficient even for JavaScript tooling
+- **markuplint is JSON-based** -- Flat Config assumes JavaScript. HTML/markup developers (the primary audience) benefit from JSON's schema validation and language-agnostic editing
+- **markuplint's `nodeRules`/`childNodeRules` are CSS-selector-based** -- These have no equivalent in Flat Config's file-pattern model
+- **ESLint v9 migration caused significant community pain** -- The gradual transition required automated migration tools and years of ecosystem adaptation
+
+**Conclusion:** Improving the JSON-based `extends` merge strategy is the optimal approach for markuplint.
+
+### Merge Strategy Principles
+
+There is a logical distinction between how arrays are handled:
+
+| Array Type                | Examples                               | Merge Behavior | Rationale                              |
+| ------------------------- | -------------------------------------- | -------------- | -------------------------------------- |
+| **Top-level collections** | `plugins`, `excludeFiles`, `nodeRules` | Accumulate     | Independent items forming a collection |
+| **Rule values**           | `["allowed-tag-1", "allowed-tag-2"]`   | Override       | A single rule's configuration value    |
+
+This aligns with ESLint and Biome, where rule values are always overridden by the more specific config.
+
+### Shallow Merge over Deep Merge
+
+| Tool       | Rule options merge           | Rationale                                                             |
+| ---------- | ---------------------------- | --------------------------------------------------------------------- |
+| ESLint     | Complete replacement         | Simplest, but can be surprising                                       |
+| Biome      | Deep merge (via Merge trait) | Full flexibility, higher complexity                                   |
+| markuplint | **Shallow merge**            | Middle ground: top-level keys are merged, nested objects are replaced |
+
+The `deepmerge` library was removed in favor of simple object spread (`{...a, ...b}`). This is sufficient because all merged objects in markuplint config (parser, specs, parserOptions, severity, plugin settings, rule options) are flat key-value maps.
+
+## Documentation Map
+
+- [Migration Guide](../../docs/migration/v4-v5/config.md) -- Breaking changes between major versions
+- [Maintenance Guide](docs/maintenance.md) -- Commands, recipes, and troubleshooting