@markuplint/selector 4.7.6 → 4.7.8

package/ARCHITECTURE.ja.md

@@ -0,0 +1,243 @@
+# @markuplint/selector
+
+## 概要
+
+`@markuplint/selector` は markuplint のための拡張 [W3C Selectors Level 4](https://www.w3.org/TR/selectors-4/) マッチャーです。2 つの独立したマッチングシステムを提供します:
+
+1. **CSS セレクタマッチング** -- `postcss-selector-parser` を使用して標準 CSS セレクタをパースし、DOM ノードに対して完全な詳細度追跡付きでマッチングします。
+2. **Regex セレクタマッチング** -- ノード名と属性に対する正規表現パターンでマッチングし、キャプチャグループデータを抽出します。
+
+また、markuplint 固有の拡張擬似クラス（`:aria()`、`:role()`、`:model()`）を定義し、HTML/ARIA 仕様データをセレクタマッチングに統合します。
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts                                — エクスポートエントリーポイント
+├── types.ts                                — 型定義（Specificity, SelectorResult, RegexSelector 等）
+├── selector.ts                             — コア Selector/Ruleset/StructuredSelector/SelectorTarget クラス
+├── create-selector.ts                      — インスタンスキャッシュと拡張擬似クラス登録を持つ Selector ファクトリ
+├── match-selector.ts                       — CSS/Regex セレクタマッチング公開関数
+├── compare-specificity.ts                  — 詳細度比較ユーティリティ
+├── regex-selector-matches.ts               — 正規表現パターンマッチングヘルパー
+├── is.ts                                   — DOM ノード型ガード
+├── 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`                                                    |
+| `selector.ts`                   | CSS セレクタエンジン     | `Selector` クラス（エントリーポイントからは再エクスポートされない）、`Ruleset`, `StructuredSelector`, `SelectorTarget`（内部） |
+| `create-selector.ts`            | キャッシュ付きファクトリ | `createSelector()`                                                                                                             |
+| `match-selector.ts`             | 統合マッチング           | `matchSelector()`, `SelectorMatches`                                                                                           |
+| `compare-specificity.ts`        | 詳細度比較               | `compareSpecificity()`                                                                                                         |
+| `regex-selector-matches.ts`     | Regex マッチングヘルパー | `regexSelectorMatches()`                                                                                                       |
+| `is.ts`                         | DOM 型ガード             | `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` オブジェクトの両方を受け付ける統合マッチング関数です。`{ 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 セレクタ文字列がパースできない場合にスローされるカスタムエラーです。
+
+## コア内部クラス
+
+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 にパースされ、DOM ノードに対してマッチングされます:
+
+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: Element) => SelectorResult>;
+```
+
+3 つの擬似クラスが組み込まれています:
+
+| 擬似クラス                                     | モジュール                      | 説明                                                                   |
+| ---------------------------------------------- | ------------------------------- | ---------------------------------------------------------------------- |
+| `:aria(has name)` / `:aria(has no name)`       | `aria-pseudo-class.ts`          | `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,243 @@
+# @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 DOM nodes 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 (Specificity, SelectorResult, RegexSelector, 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                                   — DOM node type guards
+├── 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`                                       |
+| `selector.ts`                   | CSS selector engine    | `Selector` class (not re-exported from entry point), `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`                         | DOM 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. 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.
+
+## 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 DOM nodes. 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: Element) => 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 using `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,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-## [4.7.6](https://github.com/markuplint/markuplint/compare/@markuplint/selector@4.7.5...@markuplint/selector@4.7.6) (2025-08-24)
+## [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)
 
+**Note:** Version bump only for package @markuplint/selector
 
 ## [4.7.5](https://github.com/markuplint/markuplint/compare/@markuplint/selector@4.7.4...@markuplint/selector@4.7.5) (2025-08-13)
 

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.

package/SKILL.md

@@ -0,0 +1,126 @@
+---
+description: Perform maintenance tasks for @markuplint/selector
+---
+
+# selector-maintenance
+
+Perform maintenance tasks for `@markuplint/selector`: add extended pseudo-classes,
+support new CSS selectors, debug matching issues, and update dependencies.
+
+## Input
+
+`$ARGUMENTS` specifies the task. Supported tasks:
+
+| Task                               | Description                                  |
+| ---------------------------------- | -------------------------------------------- |
+| `add-pseudo-class <name>`          | Add a new extended pseudo-class              |
+| `add-selector-support <type>`      | Add support for a new CSS selector type      |
+| `debug-matching <selector> <html>` | Debug selector matching against HTML         |
+| `update-deps`                      | Update dependencies and verify compatibility |
+
+If omitted, defaults to `add-pseudo-class`.
+
+## Reference
+
+Before executing any task, read `docs/maintenance.md` (or `docs/maintenance.ja.md`)
+for the full guide. The recipes there are the source of truth for procedures.
+
+Also read:
+
+- `docs/matching.md` -- Selector matching algorithm details
+- `ARCHITECTURE.md` -- Package overview, module map, and class hierarchy
+
+## Task: add-pseudo-class
+
+Add a new markuplint-specific extended pseudo-class. Follow recipe #1 in `docs/maintenance.md`.
+
+### Step 1: Create the handler
+
+1. Read existing handlers in `src/extended-selector/` to understand the pattern
+2. Create `src/extended-selector/<name>-pseudo-class.ts`
+3. Implement the handler following the `ExtendedPseudoClass` signature:
+   ```typescript
+   (content: string) => (el: Element) => SelectorResult;
+   ```
+4. Return specificity `[0, 1, 0]` for consistency with other extended pseudo-classes
+
+### Step 2: Register the handler
+
+1. Open `src/create-selector.ts`
+2. Import the new handler
+3. Add it to the extended object in `createSelector()` when `specs` is provided
+
+### Step 3: Test and document
+
+1. Add tests in `src/create-selector.spec.ts` or a new test file
+2. Update `README.md` extended selector table
+3. Build: `yarn build --scope @markuplint/selector`
+4. Run tests: `yarn test --scope @markuplint/selector`
+
+## Task: add-selector-support
+
+Add support for a currently unsupported CSS pseudo-class. Follow recipe #2 in `docs/maintenance.md`.
+
+### Step 1: Implement matching
+
+1. Read `src/selector.ts`, find the `pseudoMatch()` function
+2. Move the target pseudo-class from the unsupported case list
+3. Add a new case with matching implementation
+4. Ensure correct specificity assignment
+
+### Step 2: Test and document
+
+1. Add tests covering the new selector
+2. Update `README.md` support table (change `❌` to `✅`)
+3. Build: `yarn build --scope @markuplint/selector`
+4. Run tests: `yarn test --scope @markuplint/selector`
+
+## Task: debug-matching
+
+Debug why a selector matches or doesn't match against given HTML.
+
+### Step 1: Set up the environment
+
+1. Read `src/selector.ts` and `src/match-selector.ts` to understand the matching flow
+2. Identify whether the selector is a CSS string or a `RegexSelector` object
+
+### Step 2: Trace the matching
+
+1. Enable debug logging: `DEBUG=selector* yarn test --scope @markuplint/selector`
+2. For CSS selectors, trace through:
+   - `Ruleset.parse()` -- Check that the selector parses correctly
+   - `StructuredSelector` -- Check the `SelectorTarget` chain
+   - `SelectorTarget` -- Check each compound selector component
+3. For regex selectors, trace through:
+   - `regexSelectorMatches()` -- Check pattern matching results
+   - `SelectorTarget.match()` -- Check combinator traversal
+
+### Step 3: Report findings
+
+1. Identify the exact point where matching succeeds or fails
+2. Check if the issue is in parsing, matching, or specificity calculation
+3. Suggest a fix or workaround
+
+## Task: update-deps
+
+Update package dependencies and verify compatibility.
+
+1. Read `package.json` for current dependency versions
+2. Check for available updates
+3. For `postcss-selector-parser` updates:
+   - Review the changelog for breaking AST or API changes
+   - Refer to recipe #3 in `docs/maintenance.md` for the integration surface
+4. For `@markuplint/ml-spec` updates:
+   - Check for type changes affecting extended pseudo-classes
+5. Update dependencies
+6. Build: `yarn build --scope @markuplint/selector`
+7. Run tests: `yarn test --scope @markuplint/selector`
+8. Verify no regressions in selector matching
+
+## Rules
+
+1. **Always build after source changes.** Run `yarn build --scope @markuplint/selector` before testing.
+2. **All extended pseudo-classes use `[0, 1, 0]` specificity.** Maintain this consistency.
+3. **CSS matching uses postcss-selector-parser AST.** Never manually parse CSS selector strings.
+4. **Regex matching is separate from CSS matching.** They share the `matchSelector()` entry point but use different code paths.
+5. **Selector instances are cached.** After changing parsing or matching logic, the cache may return stale instances in tests. Clear the cache or restart the test runner.