@markuplint/selector 4.7.7 → 5.0.0-alpha.0

package/ARCHITECTURE.ja.md

@@ -0,0 +1,259 @@
+# @markuplint/selector
+
+## 概要
+
+`@markuplint/selector` は markuplint のための拡張 [W3C Selectors Level 4](https://www.w3.org/TR/selectors-4/) マッチャーです。2 つの独立したマッチングシステムを提供します:
+
+1. **CSS セレクタマッチング** -- `postcss-selector-parser` を使用して標準 CSS セレクタをパースし、要素に対して完全な詳細度追跡付きでマッチングします。
+2. **Regex セレクタマッチング** -- ノード名と属性に対する正規表現パターンでマッチングし、キャプチャグループデータを抽出します。
+
+また、markuplint 固有の拡張擬似クラス（`:aria()`、`:role()`、`:model()`）を定義し、HTML/ARIA 仕様データをセレクタマッチングに統合します。
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts                                — エクスポートエントリーポイント
+├── types.ts                                — 型定義（SelectorElement, SelectorNode, SelectorAttr, Specificity, SelectorResult 等）
+├── selector.ts                             — コア Selector/Ruleset/StructuredSelector/SelectorTarget クラス
+├── create-selector.ts                      — インスタンスキャッシュと拡張擬似クラス登録を持つ Selector ファクトリ
+├── match-selector.ts                       — CSS/Regex セレクタマッチング公開関数
+├── compare-specificity.ts                  — 詳細度比較ユーティリティ
+├── regex-selector-matches.ts               — 正規表現パターンマッチングヘルパー
+├── is.ts                                   — ノード型ガード（SelectorNode/SelectorElement）
+├── invalid-selector-error.ts               — 無効セレクタ用カスタムエラークラス
+├── debug.ts                                — デバッグログ設定（debug パッケージ使用）
+└── extended-selector/
+    ├── aria-pseudo-class.ts                — :aria() 擬似クラス（アクセシブルネーム判定）
+    ├── aria-role-pseudo-class.ts           — :role() 擬似クラス（計算された ARIA ロール判定）
+    └── content-model-pseudo-class.ts       — :model() 擬似クラス（HTML コンテンツモデルカテゴリ判定）
+```
+
+## アーキテクチャ図
+
+```mermaid
+flowchart TD
+    subgraph publicAPI ["公開 API"]
+        createSelector["createSelector()"]
+        matchSelector["matchSelector()"]
+        compareSpec["compareSpecificity()"]
+    end
+
+    subgraph cssMatching ["CSS セレクタマッチング"]
+        Selector["Selector"]
+        Ruleset["Ruleset"]
+        StructuredSelector["StructuredSelector"]
+        SelectorTarget["SelectorTarget\n(CSS)"]
+        psp["postcss-selector-parser"]
+    end
+
+    subgraph regexMatching ["Regex セレクタマッチング"]
+        RegexSelectorTarget["SelectorTarget\n(Regex)"]
+        regexSelectorMatches["regexSelectorMatches()"]
+    end
+
+    subgraph extendedPseudo ["拡張擬似クラス"]
+        aria[":aria()"]
+        role[":role()"]
+        model[":model()"]
+    end
+
+    subgraph deps ["外部依存"]
+        mlSpec["@markuplint/ml-spec"]
+    end
+
+    createSelector -->|"生成＆キャッシュ"| Selector
+    Selector -->|"パース委譲"| Ruleset
+    Ruleset -->|"パーサ呼出"| psp
+    Ruleset -->|"保持"| StructuredSelector
+    StructuredSelector -->|"チェーン"| SelectorTarget
+
+    matchSelector -->|"CSS 文字列"| createSelector
+    matchSelector -->|"RegexSelector"| RegexSelectorTarget
+    RegexSelectorTarget -->|"使用"| regexSelectorMatches
+
+    SelectorTarget -->|"ディスパッチ"| extendedPseudo
+    mlSpec -->|"仕様データ"| extendedPseudo
+```
+
+## モジュール概要
+
+| モジュール                      | 役割                     | 主要エクスポート                                                                                                               |
+| ------------------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
+| `index.ts`                      | エントリーポイント       | 全公開 API の再エクスポート                                                                                                    |
+| `types.ts`                      | 型定義                   | `Specificity`, `SelectorResult`, `RegexSelector`, `RegexSelectorCombinator`, `SelectorAttr`, `SelectorNode`, `SelectorElement` |
+| `selector.ts`                   | CSS セレクタエンジン     | `Selector` クラス、`ExtendedPseudoClass` 型、`Ruleset`, `StructuredSelector`, `SelectorTarget`（内部）                         |
+| `create-selector.ts`            | キャッシュ付きファクトリ | `createSelector()`                                                                                                             |
+| `match-selector.ts`             | 統合マッチング           | `matchSelector()`, `SelectorMatches`                                                                                           |
+| `compare-specificity.ts`        | 詳細度比較               | `compareSpecificity()`                                                                                                         |
+| `regex-selector-matches.ts`     | Regex マッチングヘルパー | `regexSelectorMatches()`                                                                                                       |
+| `is.ts`                         | ノード型ガード           | `isElement()`, `isNonDocumentTypeChildNode()`, `isPureHTMLElement()`                                                           |
+| `invalid-selector-error.ts`     | エラークラス             | `InvalidSelectorError`                                                                                                         |
+| `debug.ts`                      | デバッグログ             | `log`（debug インスタンス）, `enableDebug()`                                                                                   |
+| `aria-pseudo-class.ts`          | `:aria()` ハンドラ       | `ariaPseudoClass()`                                                                                                            |
+| `aria-role-pseudo-class.ts`     | `:role()` ハンドラ       | `ariaRolePseudoClass()`                                                                                                        |
+| `content-model-pseudo-class.ts` | `:model()` ハンドラ      | `contentModelPseudoClass()`                                                                                                    |
+
+## 公開 API
+
+### `createSelector(selector, specs?)`
+
+キャッシュされた `Selector` インスタンスを作成します。`specs` を指定すると、拡張擬似クラス（`:model()`、`:aria()`、`:role()`）が利用可能になります。インスタンスはセレクタ文字列をキーとしてキャッシュされます。
+
+### `matchSelector(el, selector, scope?, specs?)`
+
+CSS セレクタ文字列または `RegexSelector` オブジェクトの両方を受け付ける統合マッチング関数です。`el` および `scope` パラメータは任意の `SelectorNode` を受け取ります。`{ matched: true, selector, specificity, data? }` または `{ matched: false }` を返します。
+
+### `compareSpecificity(a, b)`
+
+2 つの `Specificity` タプル（`[id, class, type]`）を比較します。`-1`、`0`、`1` を返します。
+
+### `SelectorMatches`（型）
+
+セレクタマッチ結果のユニオン型: `{ matched: true, selector, specificity, data? } | { matched: false }`。
+
+### `InvalidSelectorError`
+
+CSS セレクタ文字列がパースできない場合にスローされるカスタムエラーです。
+
+## 純粋データインターフェース
+
+セレクタエンジンは DOM `Element`/`Node` を直接使用せず、純粋なデータインターフェース上で動作します。これにより、マッチングロジックが約200プロパティの DOM API から分離され、移植性（例: Rust/WASM）とプレーンオブジェクトによるテストが可能になります。
+
+| インターフェース  | 継承元         | 用途                                                   |
+| ----------------- | -------------- | ------------------------------------------------------ |
+| `SelectorAttr`    | —              | 最小属性: `name`, `localName`, `value`, `namespaceURI` |
+| `SelectorNode`    | —              | 最小ノード: `nodeType`, `nodeName`, `parentNode`       |
+| `SelectorElement` | `SelectorNode` | エンジンが実際に読み取る約12のプロパティを持つ要素     |
+
+DOM `Element`、JSDOM 要素、`MLElement` はすべて構造的型付けにより `SelectorElement` を満たします — アダプタコードは不要です。
+
+拡張擬似クラス（`:aria()`、`:role()`、`:model()`）は `SelectorElement` を受け取り、完全な DOM API が必要な `@markuplint/ml-spec` 境界で `Element` にキャストします。
+
+`@markuplint/selector` は依存グラフ上 `@markuplint/ml-core` より下位に位置するため、`MLElement` を直接参照できません。`:aria()` 擬似クラスはダックタイピング（`'getAccessibleName' in el`）により、要素がキャッシュ付きアクセシブルネームメソッドを持つかを検出します。これにより、循環依存を導入することなく `MLElement` の要素単位メモ化キャッシュをセレクタから共有できます。
+
+## コア内部クラス
+
+CSS マッチングシステムは 4 つのクラスの階層で構成されます:
+
+```
+Selector
+  └── Ruleset（postcss-selector-parser でパース）
+        └── StructuredSelector[]（カンマ区切りセレクタごとに 1 つ）
+              └── SelectorTarget[]（コンビネータで連結されたチェーン）
+```
+
+- **Selector** -- 公開クラス。マッチングと検索を `Ruleset` に委譲します。
+- **Ruleset** -- `postcss-selector-parser` でセレクタ文字列をパースし、`StructuredSelector` インスタンスのグループを保持します。カンマ区切りの全選択肢に対する `SelectorResult` 配列を返します。
+- **StructuredSelector** -- 単一のセレクタ（カンマなし）を表現します。コンビネータで連結された `SelectorTarget` ノードのチェーンを構築します。マッチング時は右から左へチェーンをたどります。
+- **SelectorTarget** -- 単一の複合セレクタを要素に対してマッチングします。ID、タグ、クラス、属性、ユニバーサルセレクタ、擬似クラス（拡張擬似クラスを含む）を処理します。
+
+## 2 つのマッチングシステム
+
+### CSS セレクタマッチング
+
+標準 CSS セレクタは `postcss-selector-parser` により AST にパースされ、`SelectorNode`/`SelectorElement` インスタンスに対してマッチングされます:
+
+1. `createSelector()` がキャッシュされた `Selector` インスタンスを作成または取得
+2. `Selector.match()` が `Ruleset.match()` に委譲
+3. 各 `StructuredSelector` が AST から `SelectorTarget` チェーンを構築
+4. `SelectorTarget` が個別の複合セレクタ（ID、クラス、タグ、属性、擬似クラス）をマッチング
+5. コンビネータ（子孫、子、兄弟）が `SelectorTarget` ノード間の DOM をトラバース
+
+### Regex セレクタマッチング
+
+Regex セレクタは `RegexSelector` 型を使用してパターンで要素をマッチングします:
+
+1. `matchSelector()` が `RegexSelector` オブジェクトを受け取る
+2. `combination` リンクから `SelectorTarget` チェーンが構築される
+3. 各ターゲットが `regexSelectorMatches()` を使用して `nodeName`、`attrName`、`attrValue` をマッチング
+4. マッチしたキャプチャグループが `data` レコード（`$0`、`$1`、名前付きグループ）に収集される
+5. コンビネータは標準 CSS コンビネータに加え、前方兄弟マッチング用の `:has(+)` と `:has(~)` を含む
+
+詳細なアルゴリズムは[セレクタマッチング](docs/matching.ja.md)を参照してください。
+
+## 拡張擬似クラスシステム
+
+拡張擬似クラスは `ExtendedPseudoClass` 型を通じて登録されます:
+
+```typescript
+type ExtendedPseudoClass = Record<string, (content: string) => (el: SelectorElement) => SelectorResult>;
+```
+
+3 つの擬似クラスが組み込まれています:
+
+| 擬似クラス                                     | モジュール                      | 説明                                                                                                                                         |
+| ---------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `:aria(has name)` / `:aria(has no name)`       | `aria-pseudo-class.ts`          | アクセシブルネームの有無で要素をマッチング（`MLElement.getAccessibleName()` のキャッシュを利用、フォールバックとして `getAccname()` を使用） |
+| `:role(roleName)` / `:role(roleName\|version)` | `aria-role-pseudo-class.ts`     | `getComputedRole()` を使用して計算された ARIA ロールで要素をマッチング                                                                       |
+| `:model(category)`                             | `content-model-pseudo-class.ts` | HTML コンテンツモデルカテゴリに属する要素をマッチング                                                                                        |
+
+すべての拡張擬似クラスの詳細度は `[0, 1, 0]` です。
+
+## 詳細度
+
+詳細度はマッチング全体を通じて `[id, class, type]` タプルとして追跡されます。主要なルール:
+
+- `:where()` は `[0, 0, 0]` の詳細度
+- `:not()`、`:is()`、`:has()` は最も詳細度の高い引数の詳細度
+- 拡張擬似クラスは `[0, 1, 0]`
+- `compareSpecificity()` は左から右に比較（ID > class > type）
+
+## 外部依存パッケージ
+
+| パッケージ                | 用途                                                      |
+| ------------------------- | --------------------------------------------------------- |
+| `postcss-selector-parser` | CSS セレクタ文字列の AST へのパース                       |
+| `@markuplint/ml-spec`     | 拡張擬似クラス用の HTML/ARIA 仕様データ                   |
+| `debug`                   | `DEBUG=selector*` によるデバッグログ                      |
+| `type-fest`               | TypeScript ユーティリティ型（`ReadonlyDeep`, `Writable`） |
+
+開発依存:
+
+| パッケージ | 用途              |
+| ---------- | ----------------- |
+| `jsdom`    | テスト用 DOM 環境 |
+
+## 他パッケージとの連携
+
+```mermaid
+flowchart LR
+    subgraph upstream ["上流パッケージ"]
+        mlSpec["@markuplint/ml-spec\n(仕様データ + 型)"]
+        psp["postcss-selector-parser\n(CSS パーサ)"]
+    end
+
+    subgraph pkg ["@markuplint/selector"]
+        createSel["createSelector()"]
+        matchSel["matchSelector()"]
+    end
+
+    subgraph downstream ["下流パッケージ"]
+        mlCore["@markuplint/ml-core"]
+        rules["@markuplint/rules"]
+        mlConfig["@markuplint/ml-config"]
+    end
+
+    mlSpec -->|"仕様データ\n(ARIA, コンテンツモデル)"| pkg
+    psp -->|"セレクタ AST"| pkg
+
+    matchSel -->|"matchSelector()"| mlCore
+    createSel -->|"createSelector().search()"| rules
+    pkg -->|"RegexSelector 型"| mlConfig
+```
+
+### 上流
+
+- **`@markuplint/ml-spec`** は拡張擬似クラスで使用される ARIA 仕様データ（`getComputedRole`、`getAccname`、`contentModelCategoryToTagNames`）と `resolveNamespace()` ユーティリティを提供します。
+- **`postcss-selector-parser`** は CSS セレクタ文字列を `Ruleset` が使用する AST にパースします。
+
+### 下流
+
+- **`@markuplint/ml-core`** はリント実行中にルール設定を要素にマッチングするために `matchSelector()` を使用します。
+- **`@markuplint/rules`** はルール実装での要素選択に `createSelector().search()` を使用します。
+- **`@markuplint/ml-config`** は設定スキーマ定義に `RegexSelector` 型を使用します。
+
+## ドキュメントマップ
+
+- [セレクタマッチング](docs/matching.ja.md) -- CSS と Regex セレクタマッチングアルゴリズムの詳細
+- [メンテナンスガイド](docs/maintenance.ja.md) -- コマンド、テスト、レシピ、トラブルシューティング

package/ARCHITECTURE.md

@@ -0,0 +1,259 @@
+# @markuplint/selector
+
+## Overview
+
+`@markuplint/selector` is an extended [W3C Selectors Level 4](https://www.w3.org/TR/selectors-4/) matcher for markuplint. It provides two independent matching systems:
+
+1. **CSS Selector Matching** -- Parses standard CSS selectors via `postcss-selector-parser` and matches them against elements with full specificity tracking.
+2. **Regex Selector Matching** -- Matches elements using regular expression patterns on node names and attributes, with captured group data extraction.
+
+The package also defines markuplint-specific extended pseudo-classes (`:aria()`, `:role()`, `:model()`) that integrate HTML/ARIA specification data into selector matching.
+
+## Directory Structure
+
+```
+src/
+├── index.ts                                — Export entry point
+├── types.ts                                — Type definitions (SelectorElement, SelectorNode, SelectorAttr, Specificity, SelectorResult, etc.)
+├── selector.ts                             — Core Selector/Ruleset/StructuredSelector/SelectorTarget classes
+├── create-selector.ts                      — Selector factory with instance caching and extended pseudo-class registration
+├── match-selector.ts                       — CSS/Regex selector matching public function
+├── compare-specificity.ts                  — Specificity comparison utility
+├── regex-selector-matches.ts               — Regex pattern matching helper
+├── is.ts                                   — Node type guards (SelectorNode/SelectorElement)
+├── invalid-selector-error.ts               — Custom error class for invalid selectors
+├── debug.ts                                — Debug log configuration (using debug package)
+└── extended-selector/
+    ├── aria-pseudo-class.ts                — :aria() pseudo-class (accessible name matching)
+    ├── aria-role-pseudo-class.ts           — :role() pseudo-class (computed ARIA role matching)
+    └── content-model-pseudo-class.ts       — :model() pseudo-class (HTML content model category matching)
+```
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph publicAPI ["Public API"]
+        createSelector["createSelector()"]
+        matchSelector["matchSelector()"]
+        compareSpec["compareSpecificity()"]
+    end
+
+    subgraph cssMatching ["CSS Selector Matching"]
+        Selector["Selector"]
+        Ruleset["Ruleset"]
+        StructuredSelector["StructuredSelector"]
+        SelectorTarget["SelectorTarget\n(CSS)"]
+        psp["postcss-selector-parser"]
+    end
+
+    subgraph regexMatching ["Regex Selector Matching"]
+        RegexSelectorTarget["SelectorTarget\n(Regex)"]
+        regexSelectorMatches["regexSelectorMatches()"]
+    end
+
+    subgraph extendedPseudo ["Extended Pseudo-Classes"]
+        aria[":aria()"]
+        role[":role()"]
+        model[":model()"]
+    end
+
+    subgraph deps ["External Dependencies"]
+        mlSpec["@markuplint/ml-spec"]
+    end
+
+    createSelector -->|"creates & caches"| Selector
+    Selector -->|"parses via"| Ruleset
+    Ruleset -->|"delegates to"| psp
+    Ruleset -->|"contains"| StructuredSelector
+    StructuredSelector -->|"chain of"| SelectorTarget
+
+    matchSelector -->|"CSS string"| createSelector
+    matchSelector -->|"RegexSelector"| RegexSelectorTarget
+    RegexSelectorTarget -->|"uses"| regexSelectorMatches
+
+    SelectorTarget -->|"dispatches"| extendedPseudo
+    mlSpec -->|"spec data"| extendedPseudo
+```
+
+## Module Overview
+
+| Module                          | Role                   | Key Exports                                                                                                                    |
+| ------------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| `index.ts`                      | Entry point            | Re-exports all public API                                                                                                      |
+| `types.ts`                      | Type definitions       | `Specificity`, `SelectorResult`, `RegexSelector`, `RegexSelectorCombinator`, `SelectorAttr`, `SelectorNode`, `SelectorElement` |
+| `selector.ts`                   | CSS selector engine    | `Selector` class, `ExtendedPseudoClass` type, `Ruleset`, `StructuredSelector`, `SelectorTarget` (internal)                     |
+| `create-selector.ts`            | Factory with caching   | `createSelector()`                                                                                                             |
+| `match-selector.ts`             | Unified matching       | `matchSelector()`, `SelectorMatches`                                                                                           |
+| `compare-specificity.ts`        | Specificity comparison | `compareSpecificity()`                                                                                                         |
+| `regex-selector-matches.ts`     | Regex matching helper  | `regexSelectorMatches()`                                                                                                       |
+| `is.ts`                         | Node type guards       | `isElement()`, `isNonDocumentTypeChildNode()`, `isPureHTMLElement()`                                                           |
+| `invalid-selector-error.ts`     | Error class            | `InvalidSelectorError`                                                                                                         |
+| `debug.ts`                      | Debug logging          | `log` (debug instance), `enableDebug()`                                                                                        |
+| `aria-pseudo-class.ts`          | `:aria()` handler      | `ariaPseudoClass()`                                                                                                            |
+| `aria-role-pseudo-class.ts`     | `:role()` handler      | `ariaRolePseudoClass()`                                                                                                        |
+| `content-model-pseudo-class.ts` | `:model()` handler     | `contentModelPseudoClass()`                                                                                                    |
+
+## Public API
+
+### `createSelector(selector, specs?)`
+
+Creates a cached `Selector` instance. When `specs` is provided, the extended pseudo-classes (`:model()`, `:aria()`, `:role()`) become available. Instances are cached by selector string for reuse.
+
+### `matchSelector(el, selector, scope?, specs?)`
+
+Unified matching function that accepts either a CSS selector string or a `RegexSelector` object. The `el` and `scope` parameters accept any `SelectorNode`. Returns `{ matched: true, selector, specificity, data? }` or `{ matched: false }`.
+
+### `compareSpecificity(a, b)`
+
+Compares two `Specificity` tuples (`[id, class, type]`). Returns `-1`, `0`, or `1`.
+
+### `SelectorMatches` (type)
+
+Union type for selector match results: `{ matched: true, selector, specificity, data? } | { matched: false }`.
+
+### `InvalidSelectorError`
+
+Custom error thrown when a CSS selector string cannot be parsed.
+
+## Pure Data Interfaces
+
+The selector engine operates on pure data interfaces rather than DOM `Element`/`Node` directly. This decouples the matching logic from the ~200-property DOM API, making it portable (e.g., to Rust/WASM) and testable with plain objects.
+
+| Interface         | Extends        | Purpose                                                         |
+| ----------------- | -------------- | --------------------------------------------------------------- |
+| `SelectorAttr`    | —              | Minimal attribute: `name`, `localName`, `value`, `namespaceURI` |
+| `SelectorNode`    | —              | Minimal node: `nodeType`, `nodeName`, `parentNode`              |
+| `SelectorElement` | `SelectorNode` | Element with the ~12 properties the engine actually reads       |
+
+DOM `Element`, JSDOM elements, and `MLElement` all satisfy `SelectorElement` via structural typing — no adapter code is needed.
+
+Extended pseudo-classes (`:aria()`, `:role()`, `:model()`) receive a `SelectorElement` and cast to `Element` at the `@markuplint/ml-spec` boundary where full DOM APIs are required.
+
+Because `@markuplint/selector` sits below `@markuplint/ml-core` in the dependency graph, it cannot reference `MLElement` directly. The `:aria()` pseudo-class uses duck-typing (`'getAccessibleName' in el`) to detect whether the element provides a cached accessible name method. This allows the selector to share `MLElement`'s per-element memoization cache without introducing a circular dependency.
+
+## Core Internal Classes
+
+The CSS matching system uses a hierarchy of four classes:
+
+```
+Selector
+  └── Ruleset (parsed from postcss-selector-parser)
+        └── StructuredSelector[] (one per comma-separated selector)
+              └── SelectorTarget[] (chain linked by combinators)
+```
+
+- **Selector** -- Public-facing class. Delegates to `Ruleset` for matching and searching.
+- **Ruleset** -- Parses a selector string via `postcss-selector-parser` and holds a group of `StructuredSelector` instances. Returns an array of `SelectorResult` for all comma-separated alternatives.
+- **StructuredSelector** -- Represents a single selector (without commas). Builds a chain of `SelectorTarget` nodes linked by combinators. Traverses the chain from right to left during matching.
+- **SelectorTarget** -- Matches a single compound selector against an element. Handles ID, tag, class, attribute, universal selectors, and pseudo-classes (including extended pseudo-classes).
+
+## Two Matching Systems
+
+### CSS Selector Matching
+
+Standard CSS selectors are parsed by `postcss-selector-parser` into an AST, then matched against `SelectorNode`/`SelectorElement` instances. The matching process:
+
+1. `createSelector()` creates or retrieves a cached `Selector` instance
+2. `Selector.match()` delegates to `Ruleset.match()`
+3. Each `StructuredSelector` builds a `SelectorTarget` chain from the AST
+4. `SelectorTarget` matches individual compounds (ID, class, tag, attributes, pseudo-classes)
+5. Combinators (descendant, child, sibling) traverse the DOM between `SelectorTarget` nodes
+
+### Regex Selector Matching
+
+Regex selectors use the `RegexSelector` type to match elements by patterns:
+
+1. `matchSelector()` receives a `RegexSelector` object
+2. A `SelectorTarget` chain is built from the `combination` links
+3. Each target matches `nodeName`, `attrName`, and/or `attrValue` using `regexSelectorMatches()`
+4. Matched capture groups are collected into a `data` record (`$0`, `$1`, named groups)
+5. Combinators include standard CSS combinators plus `:has(+)` and `:has(~)` for forward-sibling matching
+
+See [Selector Matching](docs/matching.md) for detailed algorithm documentation.
+
+## Extended Pseudo-Class System
+
+Extended pseudo-classes are registered through the `ExtendedPseudoClass` type:
+
+```typescript
+type ExtendedPseudoClass = Record<string, (content: string) => (el: SelectorElement) => SelectorResult>;
+```
+
+Three pseudo-classes are built in:
+
+| Pseudo-Class                                   | Module                          | Description                                                                                                                            |
+| ---------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `:aria(has name)` / `:aria(has no name)`       | `aria-pseudo-class.ts`          | Matches elements by accessible name presence (uses `MLElement.getAccessibleName()` cache when available, falls back to `getAccname()`) |
+| `:role(roleName)` / `:role(roleName\|version)` | `aria-role-pseudo-class.ts`     | Matches elements by computed ARIA role using `getComputedRole()`                                                                       |
+| `:model(category)`                             | `content-model-pseudo-class.ts` | Matches elements belonging to an HTML content model category                                                                           |
+
+All extended pseudo-classes have a specificity of `[0, 1, 0]`.
+
+## Specificity
+
+Specificity is tracked as a `[id, class, type]` tuple throughout matching. Key rules:
+
+- `:where()` contributes `[0, 0, 0]` specificity
+- `:not()`, `:is()`, `:has()` contribute the specificity of their most specific argument
+- Extended pseudo-classes contribute `[0, 1, 0]`
+- `compareSpecificity()` compares left-to-right (ID > class > type)
+
+## External Dependencies
+
+| Dependency                | Purpose                                                  |
+| ------------------------- | -------------------------------------------------------- |
+| `postcss-selector-parser` | CSS selector string parsing into AST                     |
+| `@markuplint/ml-spec`     | HTML/ARIA specification data for extended pseudo-classes |
+| `debug`                   | Debug logging via `DEBUG=selector*`                      |
+| `type-fest`               | TypeScript utility types (`ReadonlyDeep`, `Writable`)    |
+
+Dev dependencies:
+
+| Dependency | Purpose                   |
+| ---------- | ------------------------- |
+| `jsdom`    | DOM environment for tests |
+
+## Integration Points
+
+```mermaid
+flowchart LR
+    subgraph upstream ["Upstream"]
+        mlSpec["@markuplint/ml-spec\n(spec data + types)"]
+        psp["postcss-selector-parser\n(CSS parser)"]
+    end
+
+    subgraph pkg ["@markuplint/selector"]
+        createSel["createSelector()"]
+        matchSel["matchSelector()"]
+    end
+
+    subgraph downstream ["Downstream"]
+        mlCore["@markuplint/ml-core"]
+        rules["@markuplint/rules"]
+        mlConfig["@markuplint/ml-config"]
+    end
+
+    mlSpec -->|"spec data\n(ARIA, content models)"| pkg
+    psp -->|"selector AST"| pkg
+
+    matchSel -->|"matchSelector()"| mlCore
+    createSel -->|"createSelector().search()"| rules
+    pkg -->|"RegexSelector type"| mlConfig
+```
+
+### Upstream
+
+- **`@markuplint/ml-spec`** provides ARIA specification data (`getComputedRole`, `getAccname`, `contentModelCategoryToTagNames`) used by extended pseudo-classes and the `resolveNamespace()` utility.
+- **`postcss-selector-parser`** parses CSS selector strings into an AST consumed by `Ruleset`.
+
+### Downstream
+
+- **`@markuplint/ml-core`** uses `matchSelector()` to match rule configurations against elements during linting.
+- **`@markuplint/rules`** uses `createSelector().search()` for element selection in rule implementations.
+- **`@markuplint/ml-config`** uses the `RegexSelector` type for configuration schema definitions.
+
+## Documentation Map
+
+- [Selector Matching](docs/matching.md) -- CSS and regex selector matching algorithm details
+- [Maintenance Guide](docs/maintenance.md) -- Commands, testing, recipes, and troubleshooting

package/CHANGELOG.md

@@ -3,13 +3,24 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.7.7](https://github.com/markuplint/markuplint/compare/@markuplint/selector@4.7.6...@markuplint/selector@4.7.7) (2025-11-05)
+# [5.0.0-alpha.0](https://github.com/markuplint/markuplint/compare/v4.14.1...v5.0.0-alpha.0) (2026-02-20)
 
-**Note:** Version bump only for package @markuplint/selector
+### Bug Fixes
 
+- resolve additional eslint-plugin-unicorn v63 errors ([e58a72c](https://github.com/markuplint/markuplint/commit/e58a72c17c97bbec522f9513b99777fac6904d64))
+- use explicit `export type` for type-only re-exports ([7c77c05](https://github.com/markuplint/markuplint/commit/7c77c05619518c8d18a183132040f5b2cd0ab6ec))
 
+### Performance Improvements
 
+- **selector:** use cached getAccessibleName in :aria() pseudo-class ([42ea466](https://github.com/markuplint/markuplint/commit/42ea4665308e2b90e90856b29be939a6e8022347)), closes [#2179](https://github.com/markuplint/markuplint/issues/2179)
 
+## [4.7.8](https://github.com/markuplint/markuplint/compare/@markuplint/selector@4.7.7...@markuplint/selector@4.7.8) (2026-02-10)
+
+**Note:** Version bump only for package @markuplint/selector
+
+## [4.7.7](https://github.com/markuplint/markuplint/compare/@markuplint/selector@4.7.6...@markuplint/selector@4.7.7) (2025-11-05)
+
+**Note:** Version bump only for package @markuplint/selector
 
 ## [4.7.6](https://github.com/markuplint/markuplint/compare/@markuplint/selector@4.7.5...@markuplint/selector@4.7.6) (2025-08-24)
 

package/README.md

@@ -111,6 +111,12 @@ For example, `:role(interactive)` matches `<a>`(with `href` attr), `<button>`, a
 }
 ```
 
+## Documentation
+
+- [Architecture](ARCHITECTURE.md) ([日本語](ARCHITECTURE.ja.md)) -- Package overview, module map, and class hierarchy
+- [Selector Matching](docs/matching.md) ([日本語](docs/matching.ja.md)) -- CSS and regex selector matching algorithm details
+- [Maintenance Guide](docs/maintenance.md) ([日本語](docs/maintenance.ja.md)) -- Commands, testing, recipes, and troubleshooting
+
 ## Install
 
 [`markuplint`](https://www.npmjs.com/package/markuplint) package includes this package.