@markuplint/selector 4.7.6 → 4.7.8

package/docs/maintenance.ja.md

@@ -0,0 +1,209 @@
+# メンテナンスガイド
+
+`@markuplint/selector` の実践的な運用・メンテナンスガイド。
+
+## コマンド
+
+| コマンド                                        | 説明                              |
+| ----------------------------------------------- | --------------------------------- |
+| `yarn build --scope @markuplint/selector`       | TypeScript を `lib/` にコンパイル |
+| `yarn workspace @markuplint/selector run dev`   | ウォッチモードでコンパイル        |
+| `yarn workspace @markuplint/selector run clean` | コンパイル出力をクリーン          |
+| `yarn test --scope @markuplint/selector`        | テストを実行                      |
+
+## テスト
+
+テストは `vitest` と `jsdom`（DOM 環境）を使用します。4 つのテストファイルがパッケージをカバーしています:
+
+| テストファイル                   | カバー範囲                                                               |
+| -------------------------------- | ------------------------------------------------------------------------ |
+| `selector.spec.ts`               | コア `Selector` クラス、CSS セレクタマッチング、コンビネータ、擬似クラス |
+| `create-selector.spec.ts`        | `createSelector()` ファクトリ、キャッシュ、拡張擬似クラス統合            |
+| `match-selector.spec.ts`         | `matchSelector()` 統合関数、CSS と Regex セレクタのディスパッチ          |
+| `regex-selector-matches.spec.ts` | `regexSelectorMatches()` パターンマッチング、キャプチャグループ          |
+
+### テストの実行
+
+```bash
+# 全セレクタテストを実行
+yarn test --scope @markuplint/selector
+
+# 特定のテストファイルを実行
+yarn workspace @markuplint/selector run vitest run src/selector.spec.ts
+```
+
+## レシピ
+
+### 1. 新しい拡張擬似クラスの追加
+
+新しい markuplint 固有の擬似クラス（例: `:custom()`）を追加するには:
+
+1. `src/extended-selector/custom-pseudo-class.ts` を作成:
+
+   ```typescript
+   import type { SelectorResult } from '../types.js';
+
+   export function customPseudoClass() {
+     return (content: string) =>
+       (el: Element): SelectorResult => {
+         // content 文字列をパースして el に対してマッチング
+         const matched = /* マッチングロジック */;
+         return {
+           specificity: [0, 1, 0],
+           matched,
+           ...(matched ? { nodes: [el], has: [] } : {}),
+         };
+       };
+   }
+   ```
+
+2. `src/create-selector.ts` で登録:
+
+   ```typescript
+   import { customPseudoClass } from './extended-selector/custom-pseudo-class.js';
+
+   // createSelector() 内の extended オブジェクトに追加:
+   instance = new Selector(
+     selector,
+     specs
+       ? {
+           model: contentModelPseudoClass(specs),
+           aria: ariaPseudoClass(),
+           role: ariaRolePseudoClass(specs),
+           custom: customPseudoClass(), // ここに追加
+         }
+       : undefined,
+   );
+   ```
+
+3. `src/create-selector.spec.ts` または新規テストファイルにテストを追加
+4. `README.md` に新しい擬似クラスのドキュメントを追加
+5. ビルド: `yarn build --scope @markuplint/selector`
+
+### 2. 新しい CSS セレクタタイプのサポート追加
+
+現在サポートされていない擬似クラス（例: `:empty`）をサポートするには:
+
+1. `src/selector.ts` を開く
+2. `pseudoMatch()` 関数の switch 文を見つける
+3. 擬似クラスを「非サポート」ケースリストから新しいケースに移動して実装:
+   ```typescript
+   case ':empty': {
+     const hasChildren = el.childNodes.length === 0;
+     return {
+       specificity: [0, 1, 0],
+       matched: hasChildren,
+       ...(hasChildren ? { nodes: [el], has: [] } : {}),
+     };
+   }
+   ```
+4. 新しいセレクタのテストを追加
+5. `README.md` のサポート表を更新（`❌` を `✅` に変更）
+6. ビルド: `yarn build --scope @markuplint/selector`
+
+### 3. postcss-selector-parser メジャー更新時の対応
+
+`postcss-selector-parser` がメジャーバージョンをリリースした場合:
+
+1. 以下の破壊的変更をチェンジログで確認:
+   - AST ノード型（`parser.Selector`、`parser.Node` 等）
+   - パーサ API（`parser()`、`.processSync()`）
+   - ノードプロパティの名前と型
+2. `src/selector.ts` の主要な統合ポイント:
+   - `Ruleset.parse()` -- `parser()` と `processSync()` を使用
+   - `StructuredSelector` コンストラクタ -- `parser.Node` 型を走査
+   - `SelectorTarget` -- ノードプロパティ（`value`、`attribute`、`operator`、`raws` 等）にアクセス
+3. `package.json` の依存バージョンを更新
+4. 型エラーや API 変更を修正
+5. テストスイート全体を実行して互換性を確認
+6. ビルド: `yarn build --scope @markuplint/selector`
+
+### 4. 詳細度計算の修正
+
+詳細度が正しく計算されない場合:
+
+1. `src/compare-specificity.ts` の比較ロジックを確認
+2. `src/selector.ts` の `SelectorTarget` と `pseudoMatch()` での詳細度割り当てを確認
+3. Regex セレクタの場合、`src/match-selector.ts` の `uncombinedRegexSelect()` での詳細度追跡を確認
+4. 主要な詳細度の値:
+   - ID: `[1, 0, 0]`
+   - クラス、属性、擬似クラス: `[0, 1, 0]`
+   - タイプ（タグ）: `[0, 0, 1]`
+   - ユニバーサル: `[0, 0, 0]`
+   - `:where()`: 常に `[0, 0, 0]`
+5. 誤った計算を再現するテストケースを追加
+6. 修正して確認
+
+### 5. 新しい Regex コンビネータの追加
+
+Regex セレクタに新しいコンビネータを追加するには:
+
+1. `src/types.ts` の `RegexSelectorCombinator` 型を更新:
+   ```typescript
+   export type RegexSelectorCombinator = ' ' | '>' | '+' | '~' | ':has(+)' | ':has(~)' | ':new()';
+   ```
+2. `src/match-selector.ts` の `SelectorTarget.match()` の switch にトラバーサルロジックを追加:
+   ```typescript
+   case ':new()': {
+     // DOM トラバーサルロジックを実装
+   }
+   ```
+3. 新しいコンビネータのテストを追加
+4. ドキュメントを更新
+5. ビルド: `yarn build --scope @markuplint/selector`
+
+## トラブルシューティング
+
+### セレクタパースエラー
+
+**症状:** 有効に見えるセレクタで `InvalidSelectorError` がスローされる。
+
+**診断:**
+
+1. `postcss-selector-parser` がそのセレクタ構文をサポートしているか確認
+2. セレクタを分離してテスト:
+   ```typescript
+   import parser from 'postcss-selector-parser';
+   parser().processSync('your-selector');
+   ```
+3. 一部のセレクタには特定の `postcss-selector-parser` バージョンが必要な場合がある
+
+### マッチングの不一致
+
+**症状:** セレクタがマッチすべき時にマッチしない、またはその逆。
+
+**診断:**
+
+1. デバッグログを有効化: `DEBUG=selector* yarn test --scope @markuplint/selector`
+2. `SelectorTarget` のマッチング順序を確認 -- コンポーネントは順次チェックされ、最初の不一致で失敗
+3. HTML/SVG 要素の名前空間解決を `resolveNamespace()` で確認
+4. 拡張擬似クラスの場合、`specs` が `createSelector()` に渡されているか確認
+
+### 詳細度計算の問題
+
+**症状:** 詳細度の高いルールが優先されない。
+
+**診断:**
+
+1. `matchSelector()` または `Selector.match()` が返す詳細度の値をログ出力
+2. `compareSpecificity()` の比較ロジックを確認
+3. `:where()` が正しく `[0, 0, 0]` を返しているか確認
+4. ネストされた擬似クラス（`:not(:is(.a, .b))`）の場合、再帰的な詳細度計算をトレース
+
+## 依存関係メモ
+
+### postcss-selector-parser
+
+- `selector.ts` 全体で使用される CSS セレクタ AST を提供
+- 主要な型: `parser.Selector`、`parser.Node`、`parser.Pseudo`、`parser.Attribute`、`parser.ClassName`、`parser.Identifier`、`parser.Tag`、`parser.Universal`、`parser.Combinator`
+- メジャーバージョンの破壊的変更は AST ノード構造に影響する可能性あり
+
+### @markuplint/ml-spec
+
+- `getComputedRole()`、`getAccname()`、`contentModelCategoryToTagNames()`、`resolveNamespace()` を提供
+- `MLMLSpec` の型変更は拡張擬似クラスの実装に影響する可能性あり
+
+### jsdom（開発）
+
+- テストで DOM 環境を作成するための `JSDOM` を提供
+- `jsdom` で作成された要素はセレクタマッチングロジックが使用する標準 DOM API を持つ

package/docs/maintenance.md

@@ -0,0 +1,209 @@
+# Maintenance Guide
+
+Practical operations and maintenance guide for `@markuplint/selector`.
+
+## Commands
+
+| Command                                         | Description                  |
+| ----------------------------------------------- | ---------------------------- |
+| `yarn build --scope @markuplint/selector`       | Compile TypeScript to `lib/` |
+| `yarn workspace @markuplint/selector run dev`   | Watch mode compilation       |
+| `yarn workspace @markuplint/selector run clean` | Clean compiled output        |
+| `yarn test --scope @markuplint/selector`        | Run tests                    |
+
+## Testing
+
+Tests use `vitest` with `jsdom` as the DOM environment. Four test files cover the package:
+
+| Test File                        | Coverage                                                                  |
+| -------------------------------- | ------------------------------------------------------------------------- |
+| `selector.spec.ts`               | Core `Selector` class, CSS selector matching, combinators, pseudo-classes |
+| `create-selector.spec.ts`        | `createSelector()` factory, caching, extended pseudo-class integration    |
+| `match-selector.spec.ts`         | `matchSelector()` unified function, CSS and regex selector dispatch       |
+| `regex-selector-matches.spec.ts` | `regexSelectorMatches()` pattern matching, capture groups                 |
+
+### Running Tests
+
+```bash
+# Run all selector tests
+yarn test --scope @markuplint/selector
+
+# Run a specific test file
+yarn workspace @markuplint/selector run vitest run src/selector.spec.ts
+```
+
+## Common Recipes
+
+### 1. Adding a New Extended Pseudo-Class
+
+To add a new markuplint-specific pseudo-class (e.g., `:custom()`):
+
+1. Create `src/extended-selector/custom-pseudo-class.ts`:
+
+   ```typescript
+   import type { SelectorResult } from '../types.js';
+
+   export function customPseudoClass() {
+     return (content: string) =>
+       (el: Element): SelectorResult => {
+         // Parse content string and match against el
+         const matched = /* your matching logic */;
+         return {
+           specificity: [0, 1, 0],
+           matched,
+           ...(matched ? { nodes: [el], has: [] } : {}),
+         };
+       };
+   }
+   ```
+
+2. Register it in `src/create-selector.ts`:
+
+   ```typescript
+   import { customPseudoClass } from './extended-selector/custom-pseudo-class.js';
+
+   // In createSelector(), add to the extended object:
+   instance = new Selector(
+     selector,
+     specs
+       ? {
+           model: contentModelPseudoClass(specs),
+           aria: ariaPseudoClass(),
+           role: ariaRolePseudoClass(specs),
+           custom: customPseudoClass(), // Add here
+         }
+       : undefined,
+   );
+   ```
+
+3. Add tests in `src/create-selector.spec.ts` or a new test file
+4. Update `README.md` with the new pseudo-class documentation
+5. Build: `yarn build --scope @markuplint/selector`
+
+### 2. Adding Support for a New CSS Selector Type
+
+To support a currently unsupported pseudo-class (e.g., `:empty`):
+
+1. Open `src/selector.ts`
+2. Find the `pseudoMatch()` function's switch statement
+3. Move the pseudo-class from the "unsupported" case list to a new case with implementation:
+   ```typescript
+   case ':empty': {
+     const hasChildren = el.childNodes.length === 0;
+     return {
+       specificity: [0, 1, 0],
+       matched: hasChildren,
+       ...(hasChildren ? { nodes: [el], has: [] } : {}),
+     };
+   }
+   ```
+4. Add tests for the new selector
+5. Update `README.md` support table (change `❌` to `✅`)
+6. Build: `yarn build --scope @markuplint/selector`
+
+### 3. Handling postcss-selector-parser Major Updates
+
+When `postcss-selector-parser` releases a major version:
+
+1. Check the changelog for breaking changes in:
+   - AST node types (`parser.Selector`, `parser.Node`, etc.)
+   - Parser API (`parser()`, `.processSync()`)
+   - Node property names and types
+2. Key integration points in `src/selector.ts`:
+   - `Ruleset.parse()` -- Uses `parser()` and `processSync()`
+   - `StructuredSelector` constructor -- Walks `parser.Node` types
+   - `SelectorTarget` -- Accesses node properties (`value`, `attribute`, `operator`, `raws`, etc.)
+3. Update the dependency version in `package.json`
+4. Fix any type errors or API changes
+5. Run the full test suite to verify compatibility
+6. Build: `yarn build --scope @markuplint/selector`
+
+### 4. Fixing Specificity Calculation
+
+If specificity is calculated incorrectly:
+
+1. Check `src/compare-specificity.ts` for comparison logic
+2. Check `src/selector.ts` for specificity assignment in `SelectorTarget` and `pseudoMatch()`
+3. For regex selectors, check `src/match-selector.ts` `uncombinedRegexSelect()` for specificity tracking
+4. Key specificity values:
+   - ID: `[1, 0, 0]`
+   - Class, attribute, pseudo-class: `[0, 1, 0]`
+   - Type (tag): `[0, 0, 1]`
+   - Universal: `[0, 0, 0]`
+   - `:where()`: Always `[0, 0, 0]`
+5. Add a test case reproducing the incorrect calculation
+6. Fix and verify
+
+### 5. Adding a New Regex Combinator
+
+To add a new combinator for regex selectors:
+
+1. Update the `RegexSelectorCombinator` type in `src/types.ts`:
+   ```typescript
+   export type RegexSelectorCombinator = ' ' | '>' | '+' | '~' | ':has(+)' | ':has(~)' | ':new()';
+   ```
+2. Add the traversal logic in `src/match-selector.ts` in the `SelectorTarget.match()` switch:
+   ```typescript
+   case ':new()': {
+     // Implement DOM traversal logic
+   }
+   ```
+3. Add tests for the new combinator
+4. Update documentation
+5. Build: `yarn build --scope @markuplint/selector`
+
+## Troubleshooting
+
+### Selector Parse Errors
+
+**Symptom:** `InvalidSelectorError` thrown for a valid-looking selector.
+
+**Diagnosis:**
+
+1. Check if `postcss-selector-parser` supports the selector syntax
+2. Test the selector in isolation:
+   ```typescript
+   import parser from 'postcss-selector-parser';
+   parser().processSync('your-selector');
+   ```
+3. Some selectors may require specific `postcss-selector-parser` versions
+
+### Matching Mismatches
+
+**Symptom:** A selector matches or doesn't match when it should/shouldn't.
+
+**Diagnosis:**
+
+1. Enable debug logging: `DEBUG=selector* yarn test --scope @markuplint/selector`
+2. Check the `SelectorTarget` matching order -- components are checked sequentially and fail on first mismatch
+3. Verify namespace resolution for HTML/SVG elements using `resolveNamespace()`
+4. For extended pseudo-classes, verify that `specs` are being passed to `createSelector()`
+
+### Specificity Calculation Issues
+
+**Symptom:** Rules with higher specificity are not taking precedence.
+
+**Diagnosis:**
+
+1. Log the specificity values returned by `matchSelector()` or `Selector.match()`
+2. Check `compareSpecificity()` comparison logic
+3. Verify `:where()` is correctly returning `[0, 0, 0]`
+4. For nested pseudo-classes (`:not(:is(.a, .b))`), trace through the recursive specificity calculation
+
+## Dependency Notes
+
+### postcss-selector-parser
+
+- Provides the CSS selector AST used throughout `selector.ts`
+- Key types: `parser.Selector`, `parser.Node`, `parser.Pseudo`, `parser.Attribute`, `parser.ClassName`, `parser.Identifier`, `parser.Tag`, `parser.Universal`, `parser.Combinator`
+- Breaking changes in major versions may affect AST node structure
+
+### @markuplint/ml-spec
+
+- Provides `getComputedRole()`, `getAccname()`, `contentModelCategoryToTagNames()`, `resolveNamespace()`
+- Type changes in `MLMLSpec` may affect extended pseudo-class implementations
+
+### jsdom (dev)
+
+- Provides `JSDOM` for creating DOM environments in tests
+- Elements created via `jsdom` have standard DOM APIs used by the selector matching logic

package/docs/matching.ja.md

@@ -0,0 +1,211 @@
+# セレクタマッチング
+
+`@markuplint/selector` の 2 つのセレクタマッチングシステムの詳細ドキュメント。
+
+## 概要
+
+このパッケージは 2 つの独立したマッチングシステムを提供します:
+
+1. **CSS セレクタマッチング** -- `postcss-selector-parser` でパースされる標準 CSS セレクタ
+2. **Regex セレクタマッチング** -- 正規表現を使用したパターンベースのマッチング
+
+両システムとも詳細度情報を返し、統合関数 `matchSelector()` を通じて使用できます。
+
+## CSS セレクタマッチングフロー
+
+### 1. エントリーポイント
+
+```
+createSelector(selectorString, specs?)
+  → new Selector(selectorString, extendedPseudoClasses)
+    → Ruleset.parse(selectorString, extended)
+      → postcss-selector-parser がセレクタ文字列を処理
+      → parser.Selector[] AST ノードを返却
+```
+
+### 2. パース
+
+`Ruleset.parse()` は `postcss-selector-parser` を使用してセレクタ文字列を AST にパースします。カンマ区切りの各セレクタは `parser.Selector` ノードになります。`Ruleset` は各ノードを `StructuredSelector` でラップします。
+
+### 3. StructuredSelector チェーンの構築
+
+各 `StructuredSelector` は AST ノードを走査し、コンビネータで連結された `SelectorTarget` オブジェクトのチェーンを構築します:
+
+```
+div > .class:not(.other) span
+  → SelectorTarget("div") → 子コンビネータ →
+    SelectorTarget(".class:not(.other)") → 子孫コンビネータ →
+      SelectorTarget("span")
+```
+
+チェーンは AST から左から右に構築されますが、マッチングは右から左に行われます（現在の要素から開始）。
+
+### 4. SelectorTarget マッチング
+
+各 `SelectorTarget` は複合セレクタのコンポーネントを以下の順序でマッチングします:
+
+1. **名前空間チェック** -- 存在する場合、要素の名前空間を検証（`svg` と `*` のみサポート）
+2. **ID セレクタ**（`#id`）-- `el.id` にマッチ、詳細度 `[1, 0, 0]`
+3. **タグセレクタ**（`div`）-- `el.localName` にマッチ（純粋な HTML 要素は大文字小文字非区別）、詳細度 `[0, 0, 1]`。ユニバーサルセレクタ（`*`）はタグ型として扱われますが、詳細度は加算されません。
+4. **クラスセレクタ**（`.class`）-- `el.classList` にマッチ、詳細度 `[0, 1, 0]`
+5. **属性セレクタ**（`[attr=val]`）-- 要素属性を演算子付きでマッチ、詳細度 `[0, 1, 0]`
+6. **擬似クラス**（`:not()`、`:has()` 等）-- 専用ハンドラにディスパッチ
+
+いずれかのコンポーネントがマッチに失敗すると、`SelectorTarget` 全体が失敗します（早期終了）。
+
+### 5. コンビネータマッチング
+
+`SelectorTarget` がマッチすると、`StructuredSelector` はコンビネータに従って次のターゲットへ進みます:
+
+| コンビネータ | 記号            | DOM トラバーサル                          |
+| ------------ | --------------- | ----------------------------------------- |
+| 子孫         | ` `（スペース） | `parentElement` チェーンをたどる          |
+| 子           | `>`             | 直接の `parentElement` を確認             |
+| 隣接兄弟     | `+`             | `previousElementSibling` を確認           |
+| 一般兄弟     | `~`             | `previousElementSibling` チェーンをたどる |
+
+## 擬似クラスの処理
+
+### 標準擬似クラス
+
+| 擬似クラス         | 動作                                                                         |
+| ------------------ | ---------------------------------------------------------------------------- |
+| `:not(selector)`   | 内部セレクタがマッチしない場合にマッチ。詳細度は内部セレクタに等しい。       |
+| `:is(selector)`    | いずれかの内部セレクタがマッチすればマッチ。詳細度は最も高いマッチに等しい。 |
+| `:where(selector)` | `:is()` と同じだが、常に `[0, 0, 0]` の詳細度。                              |
+| `:has(selector)`   | 子孫（またはコンビネータ `+`/`~` で兄弟）がマッチすればマッチ。              |
+| `:scope`           | スコープ要素にマッチ（スコープなしの場合はルート）。詳細度 `[0, 1, 0]`。     |
+| `:root`            | `<html>` 要素にマッチ。詳細度 `[0, 1, 0]`。                                  |
+
+### カスタム: `:closest(selector)`
+
+祖先チェーンをたどり、いずれかの祖先が内部セレクタにマッチすればマッチします。これは W3C 仕様にない markuplint の拡張です。
+
+### 拡張擬似クラス
+
+拡張擬似クラスは `ExtendedPseudoClass` レジストリを通じてディスパッチされます:
+
+#### `:aria(syntax)`
+
+| 構文          | 動作                                                |
+| ------------- | --------------------------------------------------- |
+| `has name`    | `getAccname(el)` が空でない文字列を返す場合にマッチ |
+| `has no name` | `getAccname(el)` が空文字列を返す場合にマッチ       |
+
+バージョン構文をサポート: `:aria(has name|1.2)`（バージョンパラメータはパースされますが、フィルタリングにはまだ使用されていません）。
+
+#### `:role(roleName)` / `:role(roleName|version)`
+
+`getComputedRole(specs, el, version)` が返すロールの `name` が指定された `roleName` と一致する場合にマッチします。バージョンのデフォルトは `ARIA_RECOMMENDED_VERSION` です。
+
+#### `:model(category)`
+
+指定された HTML コンテンツモデルカテゴリに要素が属する場合にマッチします。`contentModelCategoryToTagNames()` を使用してカテゴリのマッチングセレクタリストを取得し、各セレクタを要素に対してテストします。
+
+特殊ケース:
+
+- `#custom` -- カスタム要素（`isCustomElement` プロパティを持つ要素）にマッチ
+- `#text` -- 常にマッチしない（テキストノードは要素ではない）
+
+## Regex セレクタマッチングフロー
+
+### 1. エントリーポイント
+
+```
+matchSelector(el, regexSelector)
+  → regexSelect(el, regexSelector)
+    → combination リンクから SelectorTarget チェーンを構築
+    → エッジ（最深の combination）からルートへ向かってマッチング
+```
+
+### 2. SelectorTarget チェーンの構築
+
+`RegexSelector` 型はチェーンされた combination をサポートします:
+
+```typescript
+{
+  nodeName: "/^div$/",
+  combination: {
+    combinator: ">",
+    nodeName: "/^span$/",
+    combination: {
+      combinator: "+",
+      attrName: "/^data-/"
+    }
+  }
+}
+```
+
+これにより次のチェーンが構築されます: `SelectorTarget(div) → > → SelectorTarget(span) → + → SelectorTarget([data-*])`
+
+### 3. パターンマッチング
+
+`regexSelectorMatches(pattern, value, ignoreCase)` がパターンマッチングを処理します:
+
+- **プレーン文字列**: `^pattern$` としてラップ（完全一致）
+- **正規表現リテラル**（`/pattern/flags`）: 指定されたフラグでそのまま使用
+- **大文字小文字の区別**: HTML 要素は大文字小文字を区別しないマッチングを使用（`isPureHTMLElement()` の場合 `ignoreCase = true`）
+
+### 4. Regex コンビネータ
+
+標準 CSS コンビネータに加え、2 つの追加コンビネータをサポートします:
+
+| コンビネータ | 記号        | DOM トラバーサル                          |
+| ------------ | ----------- | ----------------------------------------- |
+| 子孫         | `' '`       | `parentElement` チェーンをたどる          |
+| 子           | `'>'`       | 直接の `parentElement` を確認             |
+| 隣接兄弟     | `'+'`       | `previousElementSibling` を確認           |
+| 一般兄弟     | `'~'`       | `previousElementSibling` チェーンをたどる |
+| 前方隣接兄弟 | `':has(+)'` | `nextElementSibling` を確認               |
+| 前方一般兄弟 | `':has(~)'` | `nextElementSibling` チェーンをたどる     |
+
+### 5. データキャプチャ
+
+マッチした正規表現キャプチャグループは `data` オブジェクトに収集されます:
+
+```typescript
+// パターン: "/^(?<prefix>[a-z]+)-(?<suffix>[a-z]+)$/"
+// 値: "data-value"
+// 結果: { $0: "data-value", $1: "data", $2: "value", prefix: "data", suffix: "value" }
+```
+
+`nodeName` マッチングの `$0` キャプチャは削除されます（完全一致であり、要素名と冗長なため）。チェーン内の全ターゲットのデータはマージされます。
+
+### 6. 詳細度の計算
+
+Regex セレクタの詳細度はターゲットごとに計算されます:
+
+- `nodeName` マッチ: `[0, 0, 1]`（タイプ詳細度）
+- マッチした各属性: `[0, 1, 0]`（クラスレベル詳細度）
+- 結合されたターゲットの詳細度は合算されます
+
+## キャッシュ
+
+`createSelector()` は `Map<string, Selector>` キャッシュを保持します。同じセレクタ文字列での後続の呼び出しは同じ `Selector` インスタンスを返し、`postcss-selector-parser` による繰り返しのパースを回避します。
+
+## サポート対象・非対象セレクタ
+
+### サポート対象
+
+- ユニバーサル（`*`）、タイプ（`div`）、ID（`#id`）、クラス（`.class`）
+- 全属性セレクタ演算子（`=`、`~=`、`|=`、`*=`、`^=`、`$=`、大文字小文字非区別 `i` フラグ）
+- コンビネータ: 子孫（` `）、子（`>`）、隣接兄弟（`+`）、一般兄弟（`~`）
+- 複数セレクタ（`,`）
+- `:not()`、`:is()`、`:where()`、`:has()`、`:scope`、`:root`
+- `:closest()`（markuplint 拡張）
+- 拡張: `:aria()`、`:role()`、`:model()`
+- 名前空間セレクタ（`svg|text`、`*|div`）。注: `svg` と `*` の名前空間のみサポート。他の名前空間（例: `html`）は `InvalidSelectorError` をスローします。
+
+### 非サポート（エラーをスロー）
+
+構造擬似クラス: `:empty`、`:nth-child()`、`:nth-last-child()`、`:first-child`、`:last-child`、`:only-child`、`:nth-of-type()`、`:nth-last-of-type()`、`:first-of-type`、`:last-of-type`、`:only-of-type`、`:nth-col()`、`:nth-last-col()`
+
+入力擬似クラス: `:enable`、`:disable`、`:read-write`、`:read-only`、`:placeholder-shown`、`:default`、`:checked`、`:indeterminate`、`:valid`、`:invalid`、`:in-range`、`:out-of-range`、`:required`、`:optional`、`:blank`、`:user-invalid`
+
+### 無視（エラーをスロー）
+
+ユーザーインタラクション/動的擬似クラス: `:dir()`、`:lang()`、`:any-link`、`:link`、`:visited`、`:local-link`、`:target`、`:target-within`、`:current`、`:past`、`:future`、`:active`、`:hover`、`:focus`、`:focus-within`、`:focus-visible`
+
+擬似要素: `::before`、`::after`
+
+カラムコンビネータ: `||`