@markuplint/ml-core 4.13.3 → 5.0.0-alpha.1

package/ARCHITECTURE.ja.md

@@ -44,6 +44,8 @@ src/
 │   └── manipulations/
 │       ├── child-node-methods.ts     — ChildNode インターフェーススタブ
 │       └── get-children.ts           — 要素の子要素抽出
+├── virtual-rule.ts                   — Named nodeRule の展開（expandNamedNodeRules）
+├── virtual-rule.spec.ts              — 仮想ルールのユニットテスト
 ├── ml-rule/
 │   ├── ml-rule.ts                    — MLRule クラス（ルール実行）
 │   ├── ml-rule-context.ts            — MLRuleContext（レポート収集）
@@ -173,7 +175,7 @@ MLToken<A extends MLASTToken>
 | `MLText`             | `Text`               | テキストノード、`isWhitespace()`, `isRawTextElementContent()`                        |
 | `MLComment`          | `Comment`            | コメントノード（`textContent`）                                                      |
 | `MLDocumentType`     | `DocumentType`       | `<!DOCTYPE>`（`name`, `publicId`, `systemId`）                                       |
-| `MLBlock`            | —                    | プリプロセッサ固有ブロック（if/each/switch）、`conditionalType`, `isTransparent`     |
+| `MLBlock`            | —                    | プリプロセッサ固有ブロック（if/each/switch）、`blockBehavior`, `isTransparent`       |
 | `MLElementCloseTag`  | —                    | 開始タグ要素とペアになる閉じタグ                                                     |
 | `MLParentNode`       | `ParentNode`         | `querySelector()`, `querySelectorAll()`, `children`, `childElementCount`             |
 | `MLElement`          | `Element`            | 属性、セレクタ、名前空間、pretender コンテキスト、`elementType`, `closeTag`          |
@@ -204,14 +206,14 @@ MLToken<A extends MLASTToken>
 
 ### 主要メソッド
 
-| メソッド                          | 説明                                                                                          |
-| --------------------------------- | --------------------------------------------------------------------------------------------- |
-| `walkOn(type, walker)`            | 指定した型（`'Element'`, `'Text'`, `'Comment'`, `'Attr'`, `'ElementCloseTag'`）のノードを走査 |
-| `setRule(rule)`                   | 現在のルールを設定（検証時に `MLCore` が使用）                                                |
-| `getTokenList()`                  | ソース再構築用の全トークンを返す                                                              |
-| `searchNodeByLocation(line, col)` | 指定したソース位置のノードを検索                                                              |
-| `getAccessibilityProp(node)`      | ARIA アクセシビリティプロパティを計算                                                         |
-| `toString(fixed?)`                | ソースコードを再構築（オプションで修正適用）                                                  |
+| メソッド                          | 説明                                                                                                                |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
+| `walkOn(type, walker)`            | 指定した型（`'Element'`, `'Text'`, `'Comment'`, `'Attr'`, `'ElementCloseTag'`）のノードを走査                       |
+| `setRule(rule)`                   | 現在のルールを設定（検証時に `MLCore` が使用）                                                                      |
+| `getTokenList()`                  | ソース再構築用の全トークンを返す                                                                                    |
+| `searchNodeByLocation(line, col)` | 指定したソース位置のノードを検索                                                                                    |
+| `getAccessibilityProp(node)`      | ARIA アクセシビリティプロパティを計算（`MLElement.getAccessibleName()` のキャッシュ経由でアクセシブルネームを取得） |
+| `toString(fixed?)`                | ソースコードを再構築（オプションで修正適用）                                                                        |
 
 ## MLElement
 
@@ -232,15 +234,16 @@ MLToken<A extends MLASTToken>
 
 ### 主要メソッド
 
-| メソッド                     | 説明                                                           |
-| ---------------------------- | -------------------------------------------------------------- |
-| `getAttribute(name)`         | 属性値または `null` を返す                                     |
-| `getAttributeToken(name)`    | 名前付き属性の `MLAttr[]` を返す                               |
-| `hasAttribute(name)`         | 属性の存在を確認                                               |
-| `matches(selector)`          | CSS セレクタマッチング                                         |
-| `matchMLSelector(selector)`  | 拡張 markuplint セレクタマッチング（`RegexSelector` サポート） |
-| `querySelector(selector)`    | 最初にマッチする子孫を検索                                     |
-| `querySelectorAll(selector)` | マッチするすべての子孫を検索                                   |
+| メソッド                     | 説明                                                                |
+| ---------------------------- | ------------------------------------------------------------------- |
+| `getAttribute(name)`         | 属性値または `null` を返す                                          |
+| `getAttributeToken(name)`    | 名前付き属性の `MLAttr[]` を返す                                    |
+| `hasAttribute(name)`         | 属性の存在を確認                                                    |
+| `getAccessibleName(version)` | キャッシュ付きアクセシブルネーム計算（ARIA バージョンごとにメモ化） |
+| `matches(selector)`          | CSS セレクタマッチング                                              |
+| `matchMLSelector(selector)`  | 拡張 markuplint セレクタマッチング（`RegexSelector` サポート）      |
+| `querySelector(selector)`    | 最初にマッチする子孫を検索                                          |
+| `querySelectorAll(selector)` | マッチするすべての子孫を検索                                        |
 
 ## ルールシステム
 
@@ -248,13 +251,17 @@ MLToken<A extends MLASTToken>
 
 `MLRule<T, O>` はリンティングルールを検証およびオプションの修正ロジックとともにカプセル化します。
 
-| プロパティ/メソッド               | 説明                                     |
-| --------------------------------- | ---------------------------------------- |
-| `name`                            | ルール識別子（例：`"attr-duplication"`） |
-| `defaultSeverity`                 | デフォルトの重大度レベル                 |
-| `defaultValue` / `defaultOptions` | デフォルト設定                           |
-| `verify(document, locale, fix)`   | ルールを実行して違反を返す               |
-| `optimizeOption(settings)`        | 生のルール設定を `RuleInfo` に正規化     |
+| プロパティ/メソッド               | 説明                                                                            |
+| --------------------------------- | ------------------------------------------------------------------------------- |
+| `name`                            | ルール識別子（例：`"attr-duplication"`）                                        |
+| `defaultSeverity`                 | デフォルトの重大度レベル                                                        |
+| `defaultValue` / `defaultOptions` | デフォルト設定                                                                  |
+| `baseRuleId`                      | 仮想ルールの場合: ベースルール名（例：`"required-attr"`）                       |
+| `groupName`                       | 複数エントリ仮想ルールの場合: 一括無効化用のグループ名                          |
+| `specConformance`                 | 仮想ルールの場合: `'normative'` または `'non-normative'`（named nodeRule 由来） |
+| `verify(document, locale, fix)`   | ルールを実行して違反を返す                                                      |
+| `createAlias(name, options?)`     | このルールの verify/fix ロジックを再利用する仮想ルールを作成                    |
+| `optimizeOption(settings)`        | 生のルール設定を `RuleInfo` に正規化                                            |
 
 ### RuleSeed
 
@@ -310,6 +317,56 @@ flowchart TD
     G --> H["Violation[] を返す"]
 ```
 
+### 仮想ルールシステム
+
+ソース: `src/virtual-rule.ts`
+
+> **用語ポリシー**: 「仮想ルール (virtual rule)」は**コントリビューター向けの内部実装用語**です。ユーザー向けドキュメント（ウェブサイト、移行ガイド、README）では**「named rule」**を使用すること。設定ユーザーの視点では、**ベースルール**（例: `required-attr`）と **named rule**（例: `a11y/html-lang`）の2つの概念だけで十分です。`MLRule` のエイリアス機構という内部メカニズムを公開してはなりません。
+
+仮想ルールは、**名前付き nodeRules** — `/` を含む `name` プロパティを持つ nodeRule エントリ（例: `"a11y/html-lang"`）— から作成される独立した `MLRule` インスタンスです。これによりチェック単位の制御が可能になります: 各仮想ルールは `rules["alias/name"]: false` で個別に有効/無効化できます。
+
+#### Named NodeRule の展開
+
+`expandNamedNodeRules()` は `MLCore` の構築時に named nodeRules（および childNodeRules）を仮想ルールに変換します:
+
+```
+Named nodeRule（設定）                  仮想 MLRule（ランタイム）
+┌─────────────────────────┐           ┌──────────────────────────┐
+│ name: "a11y/html-lang"  │           │ name: "a11y/html-lang"   │
+│ specConformance: "norm."│  ──────►  │ baseRuleId: "required-attr" │
+│ selector: ":where(html)"│           │ specConformance: メタデータ│
+│ rules:                  │           │ verify/fix: ベースから   │
+│   required-attr: [lang] │           └──────────────────────────┘
+└─────────────────────────┘
+```
+
+主要な動作:
+
+- **false エントリの分離**: `rules` 内の `false` エントリは自動的に無名 nodeRule に分離され、ベースルールの specificity override としてのセマンティクスが維持される
+- **複数エントリサポート**: 非 false エントリが 2 つ以上の named nodeRule は派生名（`name/baseRuleName`）と `groupName` で作成され、グループ一括無効化が可能
+- **メタデータ**: `specConformance` は下流ツールやレポート向けのメタデータとして仮想ルールに付与される
+- **ホットリロード**: 展開前の nodeRules は `#originalNodeRules` / `#originalChildNodeRules` に保持され、`update()` で再展開可能
+
+#### なぜ `specConformance` は Named NodeRule 専用なのか
+
+`specConformance` は意図的に **named nodeRule（プリセット内）でのみ**使用可能であり、通常の組み込みルールでは使用できません。設計根拠は以下の通りです：
+
+1. **組み込みルールは既に正しいデフォルト重大度を持っている。** `permitted-contents` や `required-attr` のようなルールは本質的に normative（WHATWG の MUST 要件を強制する）であり、`defaultSeverity` は既に `'error'` に設定されています。別途 `specConformance` フラグは不要です — 重大度は組み込み済みです。
+
+2. **Named nodeRules はプリセット作成者による仕様解釈である。** `preset.html-standard.jsonc` のようなプリセットが `"html-standard/head-charset-utf8"` という named nodeRule を作成する場合、プリセット作成者は特定の仕様要件をチェックとして表現しています。`specConformance` により、その要件の RFC 2119 キーワード強度を宣言でき、下流のツールやレポートが違反の仕様由来の分類を識別できます。
+
+3. **ユーザーは自分のルールに `specConformance` を設定すべきではない。** カスタムコンポーネント（例: `<MyComponent>` の props 検証）に対するユーザー定義の nodeRule は仕様準拠チェックではなく、プロジェクトの規約です。任意のユーザー設定で `specConformance` を許可すると、「HTML 仕様がこれを要求している」と「チームがこれを好む」の区別が曖昧になります。`name` プロパティ（`/` を含む必要あり）がゲートキーパーとして機能します：named nodeRule のみが `specConformance` を持てる設計であり、named nodeRule は仕様を理解するプリセット作成者向けに設計されています。
+
+まとめ: `specConformance` は仕様由来のチェックを識別するメタデータを提供する**プリセットレベルのアノテーション**です。組み込みルールは `defaultSeverity` で独自に重大度を管理します。ユーザー定義ルールはルール設定の `severity` フィールドで直接重大度を表現します。
+
+#### 仮想ルールの無効化
+
+仮想ルールは `rules` 設定で3つのレベルで無効化できます:
+
+1. **完全一致**: `rules["a11y/html-lang"]: false`
+2. **グループ無効化**: `rules["custom/multi"]: false`（複数エントリの named nodeRule 用）
+3. **名前空間ワイルドカード**: `rules["a11y/*"]: false`（`a11y/` で始まるすべての仮想ルールを無効化）
+
 ## Pretender システム
 
 pretender システムにより、コンポーネントをリンティング時にセマンティック HTML 要素として扱うことができます。これにより、ルールがカスタムコンポーネント（例：`<MyButton>`）を標準要素（例：`<button>`）として検証できます。
@@ -338,16 +395,16 @@ type Pretender = {
 
 テンプレートエンジン（Pug, EJS, Nunjucks など）はプリプロセッサ固有のブロックを生成し、`MLBlock` ノードで表現されます。これらのブロックは子ノードを条件付きでラップできます：
 
-| `conditionalType` | テンプレート構文  | 説明               |
-| ----------------- | ----------------- | ------------------ |
-| `'if:start'`      | `{% if %}`        | 条件ブロックの開始 |
-| `'if:else'`       | `{% else %}`      | 代替分岐           |
-| `'if:end'`        | `{% endif %}`     | 条件ブロックの終了 |
-| `'each:start'`    | `{% for %}`       | ループの開始       |
-| `'each:end'`      | `{% endfor %}`    | ループの終了       |
-| `'switch:start'`  | `{% switch %}`    | switch の開始      |
-| `'switch:case'`   | `{% case %}`      | switch ケース      |
-| `'switch:end'`    | `{% endswitch %}` | switch の終了      |
+| `blockBehavior.type` | テンプレート構文  | 説明               |
+| -------------------- | ----------------- | ------------------ |
+| `'if'`               | `{% if %}`        | 条件ブロックの開始 |
+| `'if:else'`          | `{% else %}`      | 代替分岐           |
+| `'end'`              | `{% endif %}`     | 条件ブロックの終了 |
+| `'each'`             | `{% for %}`       | ループの開始       |
+| `'end'`              | `{% endfor %}`    | ループの終了       |
+| `'switch:case'`      | `{% switch %}`    | switch の開始      |
+| `'switch:default'`   | `{% case %}`      | switch ケース      |
+| `'end'`              | `{% endswitch %}` | switch の終了      |
 
 `MLNode.conditionalChildNodes()` は `NodeListOf` 配列の配列を返します（条件分岐ごとに 1 つ）。これにより、ルールは各分岐を独立して分析できます。
 

package/ARCHITECTURE.md

@@ -44,6 +44,8 @@ src/
 │   └── manipulations/
 │       ├── child-node-methods.ts     — ChildNode interface stubs
 │       └── get-children.ts           — Element children extraction
+├── virtual-rule.ts                   — Named nodeRule expansion (expandNamedNodeRules)
+├── virtual-rule.spec.ts              — Virtual rule unit tests
 ├── ml-rule/
 │   ├── ml-rule.ts                    — MLRule class (rule execution)
 │   ├── ml-rule-context.ts            — MLRuleContext (report collection)
@@ -173,7 +175,7 @@ MLToken<A extends MLASTToken>
 | `MLText`             | `Text`             | Text nodes, `isWhitespace()`, `isRawTextElementContent()`                                   |
 | `MLComment`          | `Comment`          | Comment nodes with `textContent`                                                            |
 | `MLDocumentType`     | `DocumentType`     | `<!DOCTYPE>` with `name`, `publicId`, `systemId`                                            |
-| `MLBlock`            | —                  | Preprocessor-specific blocks (if/each/switch), `conditionalType`, `isTransparent`           |
+| `MLBlock`            | —                  | Preprocessor-specific blocks (if/each/switch), `blockBehavior`, `isTransparent`             |
 | `MLElementCloseTag`  | —                  | Close tag paired with its open tag element                                                  |
 | `MLParentNode`       | `ParentNode`       | `querySelector()`, `querySelectorAll()`, `children`, `childElementCount`                    |
 | `MLElement`          | `Element`          | Attributes, selectors, namespaces, pretender context, `elementType`, `closeTag`             |
@@ -204,14 +206,14 @@ The constructor receives an `MLASTDocument`, a `Ruleset`, and an `MLSchema` tupl
 
 ### Key Methods
 
-| Method                            | Description                                                                                     |
-| --------------------------------- | ----------------------------------------------------------------------------------------------- |
-| `walkOn(type, walker)`            | Walks nodes of a given type (`'Element'`, `'Text'`, `'Comment'`, `'Attr'`, `'ElementCloseTag'`) |
-| `setRule(rule)`                   | Sets the current rule, used by `MLCore` during verification                                     |
-| `getTokenList()`                  | Returns all tokens for source reconstruction                                                    |
-| `searchNodeByLocation(line, col)` | Finds the node at a given source position                                                       |
-| `getAccessibilityProp(node)`      | Computes ARIA accessibility properties                                                          |
-| `toString(fixed?)`                | Reconstructs source code, optionally with fixes applied                                         |
+| Method                            | Description                                                                                                      |
+| --------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `walkOn(type, walker)`            | Walks nodes of a given type (`'Element'`, `'Text'`, `'Comment'`, `'Attr'`, `'ElementCloseTag'`)                  |
+| `setRule(rule)`                   | Sets the current rule, used by `MLCore` during verification                                                      |
+| `getTokenList()`                  | Returns all tokens for source reconstruction                                                                     |
+| `searchNodeByLocation(line, col)` | Finds the node at a given source position                                                                        |
+| `getAccessibilityProp(node)`      | Computes ARIA accessibility properties (delegates to `MLElement.getAccessibleName()` for cached accessible name) |
+| `toString(fixed?)`                | Reconstructs source code, optionally with fixes applied                                                          |
 
 ## MLElement
 
@@ -237,6 +239,7 @@ The constructor receives an `MLASTDocument`, a `Ruleset`, and an `MLSchema` tupl
 | `getAttribute(name)`         | Returns attribute value or `null`                                |
 | `getAttributeToken(name)`    | Returns `MLAttr[]` for the named attribute                       |
 | `hasAttribute(name)`         | Checks attribute existence                                       |
+| `getAccessibleName(version)` | Cached accessible name computation (memoized per ARIA version)   |
 | `matches(selector)`          | CSS selector matching                                            |
 | `matchMLSelector(selector)`  | Extended markuplint selector matching (supports `RegexSelector`) |
 | `querySelector(selector)`    | Finds first matching descendant                                  |
@@ -248,13 +251,17 @@ The constructor receives an `MLASTDocument`, a `Ruleset`, and an `MLSchema` tupl
 
 `MLRule<T, O>` encapsulates a linting rule with verification and optional fix logic.
 
-| Property/Method                   | Description                                       |
-| --------------------------------- | ------------------------------------------------- |
-| `name`                            | Rule identifier (e.g., `"attr-duplication"`)      |
-| `defaultSeverity`                 | Default severity level                            |
-| `defaultValue` / `defaultOptions` | Default configuration                             |
-| `verify(document, locale, fix)`   | Executes the rule and returns violations          |
-| `optimizeOption(settings)`        | Normalizes raw rule configuration into `RuleInfo` |
+| Property/Method                   | Description                                                                 |
+| --------------------------------- | --------------------------------------------------------------------------- |
+| `name`                            | Rule identifier (e.g., `"attr-duplication"`)                                |
+| `defaultSeverity`                 | Default severity level                                                      |
+| `defaultValue` / `defaultOptions` | Default configuration                                                       |
+| `baseRuleId`                      | For virtual rules: the base rule's name (e.g., `"required-attr"`)           |
+| `groupName`                       | For multi-entry virtual rules: group name for batch disable                 |
+| `specConformance`                 | For virtual rules: `'normative'` or `'non-normative'` (from named nodeRule) |
+| `verify(document, locale, fix)`   | Executes the rule and returns violations                                    |
+| `createAlias(name, options?)`     | Creates a virtual rule that reuses this rule's verify/fix logic             |
+| `optimizeOption(settings)`        | Normalizes raw rule configuration into `RuleInfo`                           |
 
 ### RuleSeed
 
@@ -310,6 +317,56 @@ flowchart TD
     G --> H["Return Violation[]"]
 ```
 
+### Virtual Rule System
+
+Source: `src/virtual-rule.ts`
+
+> **Terminology policy**: "Virtual rule" is an **internal implementation term** for contributors only. User-facing documentation (website, migration guides, README) must use **"named rule"** instead. From a config user's perspective, there are only two concepts: a **base rule** (e.g., `required-attr`) and a **named rule** (e.g., `a11y/html-lang`). The internal mechanics of `MLRule` aliasing should not be exposed.
+
+Virtual rules are independent `MLRule` instances created from **named nodeRules** — nodeRule entries with a `name` property containing `/` (e.g., `"a11y/html-lang"`). This enables per-check control: each virtual rule can be independently enabled/disabled via `rules["alias/name"]: false`.
+
+#### Named NodeRule Expansion
+
+`expandNamedNodeRules()` converts named nodeRules (and childNodeRules) into virtual rules during `MLCore` construction:
+
+```
+Named nodeRule (config)                Virtual MLRule (runtime)
+┌─────────────────────────┐           ┌──────────────────────────┐
+│ name: "a11y/html-lang"  │           │ name: "a11y/html-lang"   │
+│ specConformance: "norm."│  ──────►  │ baseRuleId: "required-attr" │
+│ selector: ":where(html)"│           │ specConformance: metadata│
+│ rules:                  │           │ verify/fix: from base    │
+│   required-attr: [lang] │           └──────────────────────────┘
+└─────────────────────────┘
+```
+
+Key behaviors:
+
+- **False entry separation**: `false` entries in `rules` are automatically separated into unnamed nodeRules, preserving their semantics as base-rule specificity overrides
+- **Multi-entry support**: Named nodeRules with 2+ non-false entries create derived names (`name/baseRuleName`) with a `groupName` for group disable
+- **Metadata**: `specConformance` is attached to the virtual rule as metadata for downstream tools and reporting
+- **Hot-reload**: Pre-expansion nodeRules are preserved in `#originalNodeRules` / `#originalChildNodeRules` so `update()` can re-expand them
+
+#### Why `specConformance` Is Restricted to Named NodeRules
+
+`specConformance` is intentionally available **only on named nodeRules** (in presets), not on regular built-in rules. The design rationale:
+
+1. **Built-in rules already have correct default severity.** Rules like `permitted-contents` or `required-attr` are inherently normative (they enforce WHATWG MUST requirements), and their `defaultSeverity` is already set to `'error'`. There is no need for a separate `specConformance` flag — the severity is baked in.
+
+2. **Named nodeRules are preset-authored spec interpretations.** When a preset like `preset.html-standard.jsonc` creates a named nodeRule `"html-standard/head-charset-utf8"`, the preset author is expressing a specific spec requirement as a check. `specConformance` lets the author declare the RFC 2119 keyword strength of that requirement, so downstream tools and reports can identify which violations originate from spec requirements and at what normative level.
+
+3. **Users should not set `specConformance` on their own rules.** A user-defined nodeRule for a custom component (e.g., validating `<MyComponent>` props) is not a spec conformance check — it is a project convention. Allowing `specConformance` on arbitrary user config would blur the distinction between "the HTML spec requires this" and "our team prefers this". The `name` property (which requires `/`) serves as a gatekeeper: only named nodeRules can carry `specConformance`, and named nodeRules are designed for preset authors who understand the spec.
+
+In summary: `specConformance` is a **preset-level annotation** that provides metadata about which spec requirements a check enforces. Built-in rules handle their own severity via `defaultSeverity`. User-defined rules express severity directly via the `severity` field in rule config.
+
+#### Virtual Rule Disable
+
+Virtual rules can be disabled at three levels in the `rules` config:
+
+1. **Exact name**: `rules["a11y/html-lang"]: false`
+2. **Group disable**: `rules["custom/multi"]: false` (for multi-entry named nodeRules)
+3. **Namespace wildcard**: `rules["a11y/*"]: false` (disables all virtual rules starting with `a11y/`)
+
 ## Pretender System
 
 The pretender system allows components to be treated as semantic HTML elements during linting. This enables rules to validate custom components (e.g., `<MyButton>`) as if they were standard elements (e.g., `<button>`).
@@ -338,18 +395,18 @@ type Pretender = {
 
 Template engines (Pug, EJS, Nunjucks, etc.) produce preprocessor-specific blocks represented by `MLBlock` nodes. These blocks can wrap child nodes conditionally:
 
-| `conditionalType` | Template Construct | Description                |
-| ----------------- | ------------------ | -------------------------- |
-| `'if:start'`      | `{% if %}`         | Start of conditional block |
-| `'if:else'`       | `{% else %}`       | Alternative branch         |
-| `'if:end'`        | `{% endif %}`      | End of conditional block   |
-| `'each:start'`    | `{% for %}`        | Start of loop              |
-| `'each:end'`      | `{% endfor %}`     | End of loop                |
-| `'switch:start'`  | `{% switch %}`     | Start of switch            |
-| `'switch:case'`   | `{% case %}`       | Switch case                |
-| `'switch:end'`    | `{% endswitch %}`  | End of switch              |
-
-`MLNode.conditionalChildNodes()` returns an array of `NodeListOf` arrays — one per conditional branch — so rules can analyze each branch independently.
+| `blockBehavior.type` | Template Construct | Description                |
+| -------------------- | ------------------ | -------------------------- |
+| `'if'`               | `{% if %}`         | Start of conditional block |
+| `'if:else'`          | `{% else %}`       | Alternative branch         |
+| `'end'`              | `{% endif %}`      | End of conditional block   |
+| `'each'`             | `{% for %}`        | Start of loop              |
+| `'end'`              | `{% endfor %}`     | End of loop                |
+| `'switch:case'`      | `{% switch %}`     | Start of switch            |
+| `'switch:default'`   | `{% case %}`       | Switch case                |
+| `'end'`              | `{% endswitch %}`  | End of switch              |
+
+`MLNode.conditionalChildNodes()` returns an array of `NodeListOf` arrays — one per conditional branch — so rules can analyze each branch independently. Note that `'each'` blocks do not start a new conditional mode (`'if'` or `'switch'`); they are flattened into `childNodes` and their content is treated as always-present rather than as an alternative branch. Only `'if'`/`'if:elseif'` and `'switch:case'` start new modes that generate null sentinels for the "empty branch" case.
 
 ## Plugin System
 

package/CHANGELOG.md

@@ -3,6 +3,60 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# [5.0.0-alpha.1](https://github.com/markuplint/markuplint/compare/v5.0.0-alpha.0...v5.0.0-alpha.1) (2026-02-22)
+
+**Note:** Version bump only for package @markuplint/ml-core
+
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
+
+### Bug Fixes
+
+- **ml-core:** improve detection of namespace ([5b507ad](https://github.com/markuplint/markuplint/commit/5b507ad7c19c5015b8ce587845d901e31dfa6518))
+- treat orphaned end tags as bogus instead of plain text ([#1575](https://github.com/markuplint/markuplint/issues/1575)) ([557199a](https://github.com/markuplint/markuplint/commit/557199a6960ab35573a544f9a33c00e98eb9967e))
+- use explicit `export type` for type-only re-exports ([7c77c05](https://github.com/markuplint/markuplint/commit/7c77c05619518c8d18a183132040f5b2cd0ab6ec))
+
+- feat(ml-core)!: adapt DOM layer to simplified AST types ([5d92f2b](https://github.com/markuplint/markuplint/commit/5d92f2be75ce0d45823fb26f72588aecee278ba3))
+
+### Features
+
+- delete htmx-parser, simplify alpine-parser, add migration guide and tests ([f8dbb09](https://github.com/markuplint/markuplint/commit/f8dbb090707d8cfbf3d859a9b868b2087064f89b))
+- **ml-core:** add directive and IDL resolution to MLAttr constructor ([ba0ad66](https://github.com/markuplint/markuplint/commit/ba0ad66585c022cdb34fda8a8191bcc9af078e07))
+- **ml-core:** add expandNamedRules for named rule groups in rules section ([7eed355](https://github.com/markuplint/markuplint/commit/7eed355075cee90b17a79c0f8a5b18213d1ce54e))
+- **ml-core:** implement VirtualRule system for named nodeRules ([864f51d](https://github.com/markuplint/markuplint/commit/864f51d54dba26c6af2bc45eea3566db5f7d8e26))
+- **ml-core:** require defaultValue for non-boolean rule types in createRule ([6c99908](https://github.com/markuplint/markuplint/commit/6c999087feff4fb8906cf47d564ee08ca8e5f450)), closes [#808](https://github.com/markuplint/markuplint/issues/808)
+- **ml-core:** the each block skips linting in childNodes ([d5ca83d](https://github.com/markuplint/markuplint/commit/d5ca83d5ec6dc9b2f40b5d6599b07cc4746f3dca))
+- **ml-core:** wire ruleCommonSettings through MLCore to Document ([28bb176](https://github.com/markuplint/markuplint/commit/28bb17601b983b3789b2ae200bd77ad887905cda))
+- **ml-spec:** add declarative directivePatterns for parser-less framework support ([ceb9aa6](https://github.com/markuplint/markuplint/commit/ceb9aa67048e3a058b40a9e4d91eb903c8ff1861))
+
+### Performance Improvements
+
+- **ml-core:** add memoization cache to MLElement.getAccessibleName() ([cdbe289](https://github.com/markuplint/markuplint/commit/cdbe289755312ee30e3f02171f42bf2c00412eea)), closes [#2179](https://github.com/markuplint/markuplint/issues/2179)
+
+### BREAKING CHANGES
+
+- Multiple breaking changes to DOM API:
+
+MLToken:
+
+- Compute end positions via getEndCol/getEndLine helpers
+  instead of storing them as private fields
+- Use \_astToken.offset/line/col directly
+
+MLElement:
+
+- Remove selfClosingSolidus property
+- Add blockBehavior: MLASTBlockBehavior | null
+
+MLBlock:
+
+- Replace conditionalType with blockBehavior property
+
+Node traversal:
+
+- Use blockBehavior?.type instead of conditionalType
+
+Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
+
 ## [4.13.3](https://github.com/markuplint/markuplint/compare/@markuplint/ml-core@4.13.2...@markuplint/ml-core@4.13.3) (2026-02-10)
 
 **Note:** Version bump only for package @markuplint/ml-core

package/docs/linting-pipeline.ja.md

@@ -32,17 +32,18 @@ constructor(params: MLCoreParams)
 
 `MLFabric` 型はリンティング設定全体を定義します：
 
-| フィールド      | 型                                | 説明                                                  |
-| --------------- | --------------------------------- | ----------------------------------------------------- |
-| `parser`        | `MLParser`                        | パーサーインスタンス（例：`@markuplint/html-parser`） |
-| `ruleset`       | `Ruleset`                         | 解決済みルール設定                                    |
-| `rules`         | `readonly MLRule[]`               | ルールインスタンスの配列                              |
-| `locale`        | `LocaleSet`                       | 違反メッセージのロケール                              |
-| `schemas`       | `MLSchema`                        | HTML/ARIA 仕様タプル                                  |
-| `parserOptions` | `ParserOptions`                   | パーサー設定オプション                                |
-| `severity`      | `{ parseError?: SeverityOption }` | 重大度オーバーライド                                  |
-| `pretenders`    | `readonly Pretender[]`            | コンポーネントから HTML へのマッピング                |
-| `configErrors`  | `readonly ConfigError[]`          | 報告する設定エラー                                    |
+| フィールド           | 型                                | 説明                                                  |
+| -------------------- | --------------------------------- | ----------------------------------------------------- |
+| `parser`             | `MLParser`                        | パーサーインスタンス（例：`@markuplint/html-parser`） |
+| `ruleset`            | `Ruleset`                         | 解決済みルール設定                                    |
+| `rules`              | `readonly MLRule[]`               | ルールインスタンスの配列                              |
+| `locale`             | `LocaleSet`                       | 違反メッセージのロケール                              |
+| `schemas`            | `MLSchema`                        | HTML/ARIA 仕様タプル                                  |
+| `parserOptions`      | `ParserOptions`                   | パーサー設定オプション                                |
+| `severity`           | `{ parseError?: SeverityOption }` | 重大度オーバーライド                                  |
+| `pretenders`         | `readonly Pretender[]`            | コンポーネントから HTML へのマッピング                |
+| `ruleCommonSettings` | `RuleCommonSettings`              | すべてのルールにグローバルに適用される共通設定        |
+| `configErrors`       | `readonly ConfigError[]`          | 報告する設定エラー                                    |
 
 ### プロパティ
 
@@ -52,8 +53,9 @@ constructor(params: MLCoreParams)
 
 ### 構築フロー
 
-1. `_parse()` — `parser.parse(sourceCode, parserOptions)` を呼び出して `MLASTDocument` を生成
-2. `_createDocument()` — AST を `MLDocument` でラップ（ruleset、schemas、オプション付き）
+1. **Named nodeRule の展開** — `expandNamedNodeRules()` が `nodeRules` と `childNodeRules` の名前付きエントリを仮想 `MLRule` インスタンスに変換。展開前のオリジナルは `#originalNodeRules` / `#originalChildNodeRules` にホットリロード用に保持。名前空間 disable プレフィックスはワイルドカードエントリ（例: `"a11y/*": false`）から事前計算される。
+2. `_parse()` — `parser.parse(sourceCode, parserOptions)` を呼び出して `MLASTDocument` を生成
+3. `_createDocument()` — AST を `MLDocument` でラップ（ruleset、schemas、オプション付き）
 
 パースが失敗した場合、`document` は `MLDocument` の代わりに `ParserError` を保持します。
 
@@ -76,7 +78,7 @@ constructor(params: MLCoreParams)
 パースされた AST から `MLDocument` を作成します：
 
 ```typescript
-new Document(ast, ruleset, schemas, {
+new Document(ast, ruleset, schemas, ruleCommonSettings, {
   filename,
   endTag,
   booleanish,
@@ -124,6 +126,7 @@ flowchart TD
 2. **未定義ルールの検出**: `setRuleNames`（設定内のルール）と `definedRuleName`（実際にロードされたルール）を比較。未定義ルールに対して `config-error` 警告を報告
 3. **設定エラー**: `configErrors` 配列を違反に変換
 4. **ルールループ**: 各ルールに対して：
+   - **仮想ルールの無効化チェック** — `rule.baseRuleId` がある場合、3つの条件を確認: 完全一致（`rules["alias"]: false`）、グループ無効化（`rules["groupName"]: false`）、名前空間ワイルドカード（`rules["scope/*"]: false`）。いずれかに該当した場合はスキップ。
    - `rule.getRuleInfo(ruleset, rule.name)` で有効性をチェック
    - `disabled && nodeRules.length === 0 && childNodeRules.length === 0` → スキップ
    - `rule.verify(document, locale, fix)` — ルールを実行
@@ -154,6 +157,7 @@ flowchart TD
 
 リンティング設定の部分更新：
 
+- Named nodeRules を仮想ルールに再展開。`ruleset` が提供されていない場合、`#originalNodeRules` / `#originalChildNodeRules`（展開前のコピー）をソースとして使用し、仮想ルール化で変換済みのエントリを失うことを防ぐ。
 - `parserOptions` が変更された場合 → 完全な再パース（`_parse()` + `_createDocument()`）
 - それ以外 → `_createDocument()` のみ（既存の AST を再利用）
 

package/docs/linting-pipeline.md

@@ -32,17 +32,18 @@ Where `MLCoreParams` extends `MLFabric` with:
 
 The `MLFabric` type defines the full linting configuration:
 
-| Field           | Type                              | Description                                       |
-| --------------- | --------------------------------- | ------------------------------------------------- |
-| `parser`        | `MLParser`                        | Parser instance (e.g., `@markuplint/html-parser`) |
-| `ruleset`       | `Ruleset`                         | Resolved rule configuration                       |
-| `rules`         | `readonly MLRule[]`               | Array of rule instances                           |
-| `locale`        | `LocaleSet`                       | Locale for violation messages                     |
-| `schemas`       | `MLSchema`                        | HTML/ARIA specification tuple                     |
-| `parserOptions` | `ParserOptions`                   | Parser configuration options                      |
-| `severity`      | `{ parseError?: SeverityOption }` | Severity overrides                                |
-| `pretenders`    | `readonly Pretender[]`            | Component-to-HTML mappings                        |
-| `configErrors`  | `readonly ConfigError[]`          | Configuration errors to report                    |
+| Field                | Type                              | Description                                       |
+| -------------------- | --------------------------------- | ------------------------------------------------- |
+| `parser`             | `MLParser`                        | Parser instance (e.g., `@markuplint/html-parser`) |
+| `ruleset`            | `Ruleset`                         | Resolved rule configuration                       |
+| `rules`              | `readonly MLRule[]`               | Array of rule instances                           |
+| `locale`             | `LocaleSet`                       | Locale for violation messages                     |
+| `schemas`            | `MLSchema`                        | HTML/ARIA specification tuple                     |
+| `parserOptions`      | `ParserOptions`                   | Parser configuration options                      |
+| `severity`           | `{ parseError?: SeverityOption }` | Severity overrides                                |
+| `pretenders`         | `readonly Pretender[]`            | Component-to-HTML mappings                        |
+| `ruleCommonSettings` | `RuleCommonSettings`              | Common settings applied globally to all rules     |
+| `configErrors`       | `readonly ConfigError[]`          | Configuration errors to report                    |
 
 ### Properties
 
@@ -52,8 +53,9 @@ The `MLFabric` type defines the full linting configuration:
 
 ### Construction Flow
 
-1. `_parse()` — Invokes `parser.parse(sourceCode, parserOptions)` to produce `MLASTDocument`
-2. `_createDocument()` — Wraps AST in `MLDocument` with ruleset, schemas, and options
+1. **Named nodeRule expansion** — `expandNamedNodeRules()` converts named entries in `nodeRules` and `childNodeRules` into virtual `MLRule` instances. The originals are preserved in `#originalNodeRules` / `#originalChildNodeRules` for hot-reload. Namespace disable prefixes are pre-computed from wildcard entries (e.g., `"a11y/*": false`).
+2. `_parse()` — Invokes `parser.parse(sourceCode, parserOptions)` to produce `MLASTDocument`
+3. `_createDocument()` — Wraps AST in `MLDocument` with ruleset, schemas, and options
 
 If parsing fails, `document` holds a `ParserError` instead of `MLDocument`.
 
@@ -76,7 +78,7 @@ If the parser throws:
 Creates `MLDocument` from the parsed AST:
 
 ```typescript
-new Document(ast, ruleset, schemas, {
+new Document(ast, ruleset, schemas, ruleCommonSettings, {
   filename,
   endTag,
   booleanish,
@@ -124,6 +126,7 @@ flowchart TD
 2. **Undefined rule detection**: Compares `setRuleNames` (rules in config) vs `definedRuleName` (rules actually loaded). Reports `config-error` warnings for undefined rules
 3. **Config errors**: Converts `configErrors` array to violations
 4. **Rule loop**: For each rule:
+   - **Virtual rule disable check** — If `rule.baseRuleId` is set, checks three disable conditions: exact name match (`rules["alias"]: false`), group disable (`rules["groupName"]: false`), or namespace wildcard (`rules["scope/*"]: false`). Skips the rule if any condition is met.
    - `rule.getRuleInfo(ruleset, rule.name)` checks enablement
    - If `disabled && nodeRules.length === 0 && childNodeRules.length === 0` → skip
    - `rule.verify(document, locale, fix)` — executes the rule
@@ -154,6 +157,7 @@ Re-parses with new source code:
 
 Partially updates the linting configuration:
 
+- Re-expands named nodeRules into virtual rules. When `ruleset` is not provided, uses `#originalNodeRules` / `#originalChildNodeRules` (pre-expansion copies) as the source to avoid losing named entries that were already transformed.
 - If `parserOptions` changed → full re-parse (`_parse()` + `_createDocument()`)
 - Otherwise → only `_createDocument()` (reuses existing AST)
 

package/docs/maintenance.ja.md

@@ -206,5 +206,5 @@ pretender は `MLDocument` コンストラクタ（`src/ml-dom/node/document.ts`
 1. `document.debugMap()` の出力を期待される構造と比較
 2. パーサー出力を確認：同じソースをパーサーで直接パースして AST を検査
 3. ゴースト要素（暗黙の HTML/head/body）が正しく処理されているか確認
-4. テンプレートエンジンの場合、`conditionalType` 付きの `MLBlock` ノードが期待される子をラップしているか確認
+4. テンプレートエンジンの場合、`blockBehavior` 付きの `MLBlock` ノードが期待される子をラップしているか確認
 5. `document.nodeList` でフラットノードリストを検査し、親子関係を確認

package/docs/maintenance.md

@@ -206,5 +206,5 @@ Changes to `@markuplint/ml-core` can affect:
 1. Compare `document.debugMap()` output with expected structure
 2. Check the parser output: parse the same source with the parser directly and inspect the AST
 3. Verify ghost elements (implicit HTML/head/body) are handled correctly
-4. For template engines, check that `MLBlock` nodes with `conditionalType` wrap the expected children
+4. For template engines, check that `MLBlock` nodes with `blockBehavior` wrap the expected children
 5. Use `document.nodeList` to inspect the flat node list and verify parent-child relationships

package/docs/ml-dom/attr.ja.md

@@ -24,6 +24,14 @@
 - `astToken.potentialName` が存在する場合 → `name` として使用する。そうでなければ `nameNode.raw` を使用する
 - `astToken.potentialValue` が存在する場合 → `value` として使用する。そうでなければ `valueNode.raw` を使用する
 
+### ディレクティブパターン解決
+
+パーサーが `astToken.potentialName` を設定していない場合、`MLAttr` コンストラクタは spec（例: `@markuplint/vue-spec`、`@markuplint/svelte-spec`）からの `directivePatterns` をチェックします。パターンが存在する場合、生の属性名とコンパイル済みパターンで `resolveDirective()` が呼び出されます。最初にマッチしたパターンが `potentialName`、`isDynamicValue`、`isDirective`、`isDuplicatable` を決定します。
+
+### IDL 属性名解決
+
+ディレクティブパターン解決の後、spec が `acceptedAttrNames` を設定しており（例: `@markuplint/react-spec` では `'idl'`、`@markuplint/svelte-spec` では `'both'`）、属性がディレクティブでない場合、コンストラクタは `@markuplint/parser-utils` の `searchIDLAttribute()` を呼び出して IDL プロパティ名を HTML コンテンツ属性名にマッピングします（例: `className` → `class`、`htmlFor` → `for`）。`'idl'` モードでは、IDL プロパティ名が候補として設定されます（例: `tabindex` → 「`tabIndex` の間違いでは？」）。`'both'` モードでは、コンテンツ名と IDL 名の両方が候補提案なしで受け入れられます。これはパーサーレベルではなくコアレベルの関心事です。
+
 ## トークン分解
 
 各属性は個々の `MLToken` インスタンスに分解されます：

package/docs/ml-dom/attr.md

@@ -24,6 +24,14 @@ The parser may provide resolved "potential" names and values for attributes wher
 - If `astToken.potentialName` exists → use it as `name`; otherwise use `nameNode.raw`
 - If `astToken.potentialValue` exists → use it as `value`; otherwise use `valueNode.raw`
 
+### Directive Pattern Resolution
+
+When `astToken.potentialName` is not set by the parser, the `MLAttr` constructor checks for `directivePatterns` from the spec (e.g., `@markuplint/vue-spec`, `@markuplint/svelte-spec`). If patterns exist, `resolveDirective()` is called with the raw attribute name and the compiled patterns. The first matching pattern determines `potentialName`, `isDynamicValue`, `isDirective`, and `isDuplicatable`.
+
+### IDL Attribute Name Resolution
+
+After directive pattern resolution, if the spec sets `acceptedAttrNames` (e.g., `'idl'` in `@markuplint/react-spec`, `'both'` in `@markuplint/svelte-spec`) and the attribute is not a directive, the constructor calls `searchIDLAttribute()` from `@markuplint/parser-utils` to map IDL property names to HTML content attribute names (e.g., `className` -> `class`, `htmlFor` -> `for`). In `'idl'` mode, the IDL property name is set as a candidate for suggestion (e.g., `tabindex` -> "Did you mean `tabIndex`?"). In `'both'` mode, both content and IDL names are accepted without suggestions. This is a core-level concern, not a parser-level one.
+
 ## Token Decomposition
 
 Each attribute is decomposed into individual `MLToken` instances: