@markuplint/types 4.8.0 → 4.8.2

package/ARCHITECTURE.ja.md

@@ -0,0 +1,252 @@
+# @markuplint/types
+
+## 概要
+
+`@markuplint/types` は、markuplint における HTML/SVG 属性値の型バリデーションシステムです。HTML Living Standard、CSS 仕様、その他の Web 標準に基づく型定義に対して属性値を検証します。
+
+文字列値と型定義を受け取り、値が型に適合するかどうかを判定します。不適合の場合は、不一致箇所の位置情報・理由・期待される値・修正候補を含む詳細なエラー結果を生成します。
+
+## ディレクトリ構成
+
+```
+src/
+├── index.ts                        # パッケージのエントリーポイント。公開APIを再エクスポート
+├── types.ts                        # 主要な型定義 (Result, Defs, CustomSyntax など)
+├── types.schema.ts                 # JSONスキーマから自動生成された型 (Type, List, Enum, Number, Directive)
+├── check.ts                        # 公開エントリーポイント: 組み込みdefsを使う check()
+├── check-base.ts                   # コアディスパッチャー: 型の形状に応じてチェッカーを振り分け
+├── check-multi-types.ts            # 複数チェッカーを試行し、最良の結果を返す
+├── match-result.ts                 # ファクトリ関数: matched(), unmatched(), matches()
+├── defs.ts                         # 組み込みHTML型定義レジストリ (Any, URL, DateTime など)
+├── css-defs.ts                     # CSS/SVG型定義 (viewBox, dasharray など)
+├── css-syntax.ts                   # css-tree フォークによるCSS構文マッチング
+├── css-overrides.ts                # css-tree組み込み構文のオーバーライド (SVGトランスフォーム)
+├── css-tokenizers.ts               # css-tree用カスタムトークナイザー (BCP-47)
+├── keyword-type.ts                 # キーワード型の解決とキャッシュ
+├── enum.ts                         # 列挙型チェッカー (大文字小文字非区別の集合メンバーシップ)
+├── list.ts                         # リスト型チェッカー (カンマ/スペース区切りのトークン列)
+├── number.ts                       # 数値型チェッカー (整数/浮動小数点と範囲制約)
+├── directive.ts                    # ディレクティブ型チェッカー (プレフィックスパターン + トークン検証)
+├── get-candidate.ts                # レーベンシュタイン距離によるタイプミス修正候補の提示
+├── debug.ts                        # デバッグロガーインスタンス
+├── primitive/                      # プリミティブ数値バリデーター
+│   ├── index.ts                    # 全プリミティブバリデーターの再エクスポート
+│   ├── is-float.ts                 # 浮動小数点数の検証
+│   ├── is-int.ts                   # 符号付き整数の検証
+│   ├── is-uint.ts                  # 符号なし整数の検証
+│   ├── is-non-zero-uint.ts         # 0以外の符号なし整数の検証
+│   ├── is-quantity.ts              # CSS数量 (数値 + 単位) の検証
+│   ├── split-unit.ts               # 数値部分と単位接尾辞の分離
+│   ├── range.ts                    # 数値範囲チェックユーティリティ
+│   └── index.spec.ts               # テスト
+├── token/                          # 位置追跡トークンシステム
+│   ├── index.ts                    # Token と TokenCollection の再エクスポート
+│   ├── token.ts                    # Token クラス: オフセット・行・列の追跡
+│   ├── token-collection.ts         # TokenCollection: パース済みトークン列と検証機能
+│   ├── types.ts                    # トークン値の型 (スカラー、配列、正規表現、数値)
+│   └── index.spec.ts               # テスト
+├── whatwg/                          # WHATWG HTML Standard に基づくバリデーター
+│   ├── check-autocomplete.ts       # autocomplete 属性の検証
+│   ├── check-datetime/             # DateTime マイクロシンタックスバリデーター群
+│   │   ├── index.ts                # 全日時フォーマットのディスパッチャー
+│   │   ├── date-string.ts          # YYYY-MM-DD
+│   │   ├── time-string.ts          # HH:MM:SS
+│   │   ├── month-string.ts         # YYYY-MM
+│   │   ├── week-string.ts          # YYYY-Www
+│   │   ├── year-string.ts          # YYYY
+│   │   ├── yearless-date-string.ts # MM-DD
+│   │   ├── duration-string.ts      # 期間フォーマット
+│   │   ├── global-date-and-time-string.ts
+│   │   ├── local-date-and-time-string.ts
+│   │   ├── time-zone-offset-string.ts
+│   │   ├── datetime-tokens.ts      # 共通トークンパターン
+│   │   └── index.spec.ts           # テスト
+│   ├── check-link-type.ts          # リンクタイプの検証 (rel 属性)
+│   ├── check-mime-type.ts          # MIMEタイプの検証
+│   ├── is-abs-url.ts               # 絶対URLの判定
+│   ├── is-browser-context-name.ts  # ブラウジングコンテキスト名の判定 (非推奨)
+│   ├── is-custom-element-name.ts   # カスタム要素名の判定
+│   ├── is-itemprop-name.ts         # itemprop 名の判定
+│   └── is-navigable-target-name.ts # ナビゲーションターゲット名の判定
+├── rfc/                             # RFC仕様に基づくバリデーター
+│   ├── is-bcp-47.ts                # BCP 47 言語タグの検証
+│   └── is-bcp-47.spec.ts           # テスト
+└── w3c/                             # W3C仕様に基づくバリデーター
+    ├── check-serialized-permissions-policy.ts  # Permissions Policy の検証
+    └── check-serialized-permissions-policy.spec.ts  # テスト
+```
+
+## アーキテクチャ図
+
+```mermaid
+flowchart TD
+    subgraph entry ["エントリーポイント"]
+        check["check(value, type)"]
+    end
+
+    subgraph dispatch ["コアディスパッチャー"]
+        checkBase["checkBase(value, type, defs)"]
+        isKeyword{"キーワード型?"}
+        isList{"リスト型?"}
+        isEnum{"列挙型?"}
+        isNumber{"数値型?"}
+        isDirective{"ディレクティブ型?"}
+    end
+
+    subgraph checkers ["個別チェッカー"]
+        checkKeywordType["checkKeywordType()"]
+        checkListFn["checkList()"]
+        checkEnumFn["checkEnum()"]
+        checkNumberFn["checkNumber()"]
+        checkDirectiveFn["checkDirective()"]
+    end
+
+    subgraph resolution ["キーワード解決"]
+        defsRegistry["defs + cssDefs レジストリ"]
+        cssSyntaxMatch["cssSyntaxMatch()"]
+        customSyntax["CustomSyntax.is()"]
+    end
+
+    subgraph result ["結果"]
+        matched["MatchedResult"]
+        unmatched["UnmatchedResult"]
+    end
+
+    check --> checkBase
+    checkBase --> isKeyword
+    isKeyword -->|文字列| checkKeywordType
+    isKeyword -->|オブジェクト| isList
+    isList -->|separator あり| checkListFn
+    isList -->|なし| isEnum
+    isEnum -->|enum あり| checkEnumFn
+    isEnum -->|なし| isNumber
+    isNumber -->|float/integer| checkNumberFn
+    isNumber -->|なし| isDirective
+    isDirective -->|directive あり| checkDirectiveFn
+
+    checkKeywordType --> defsRegistry
+    defsRegistry -->|CustomCssSyntax| cssSyntaxMatch
+    defsRegistry -->|CustomSyntax| customSyntax
+    defsRegistry -->|未定義| cssSyntaxMatch
+
+    checkListFn -->|各トークン| checkBase
+    checkDirectiveFn -->|トークン部分| checkBase
+
+    cssSyntaxMatch --> matched
+    cssSyntaxMatch --> unmatched
+    customSyntax --> matched
+    customSyntax --> unmatched
+    checkEnumFn --> matched
+    checkEnumFn --> unmatched
+    checkNumberFn --> matched
+    checkNumberFn --> unmatched
+```
+
+## 主要コンポーネント
+
+### 1. 型システム
+
+型システムは、属性値の制約を表現する型定義と、検証結果の表現方法を定めています。
+
+| ファイル          | 役割                                                                                                          |
+| ----------------- | ------------------------------------------------------------------------------------------------------------- |
+| `types.ts`        | 主要な型: `Result`, `MatchedResult`, `UnmatchedResult`, `Defs`, `CustomSyntax`, `CustomCssSyntax`             |
+| `types.schema.ts` | 自動生成された判別共用体 `Type` とそのバリアント: `KeywordDefinedType`, `List`, `Enum`, `Number`, `Directive` |
+| `match-result.ts` | ファクトリ関数 `matched()`, `unmatched()` および `matches()` ラッパー                                         |
+| `defs.ts`         | 組み込みHTML定義レジストリ (30以上の型: `Any`, `URL`, `DateTime`, `DOMID`, `BCP47` など)                      |
+| `css-defs.ts`     | CSS/SVG定義 (25以上の型: `<view-box>`, `<preserve-aspect-ratio>`, `<dasharray>` など)                         |
+
+`Type` 共用体は5つの形状に分岐する判別共用体です:
+
+- **文字列** (キーワード) -- 例: `"URL"`, `"<color>"`, `"DateTime"`
+- **`separator` を持つオブジェクト** (リスト) -- スペース区切りまたはカンマ区切りのトークン列
+- **`enum` を持つオブジェクト** (列挙) -- 許容される文字列値の固定集合
+- **`type: "float" | "integer"` を持つオブジェクト** (数値) -- 範囲制約付きの数値
+- **`directive` を持つオブジェクト** (ディレクティブ) -- プレフィックスパターンに続く型付きトークン
+
+### 2. チェックパイプライン
+
+バリデーションパイプラインは、型定義の形状を判別して適切なチェッカーに処理を振り分けます。
+
+| ファイル               | 役割                                                                                                                              |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `check.ts`             | 公開関数 `check()`。`defs` と `cssDefs` を結合し、`checkBase()` に委譲                                                            |
+| `check-base.ts`        | ディスパッチャー。`isKeyword()`, `isList()`, `isEnum()`, `isNumber()`, `isDirective()` で型を判別し、対応するチェッカーを呼び出す |
+| `keyword-type.ts`      | キーワード型の解決: `Defs` レジストリを参照し、見つからなければ `cssSyntaxMatch()` にフォールバック。結果をキャッシュ             |
+| `css-syntax.ts`        | `css-tree` のフォークを使い、カスタム型とトークナイザーを組み込んだ CSS 値定義構文マッチング                                      |
+| `enum.ts`              | 許容値の集合に対する検証 (デフォルトで大文字小文字非区別)                                                                         |
+| `list.ts`              | セパレータで値を分割し、各トークンを `checkBase()` で再帰的に検証                                                                 |
+| `number.ts`            | 整数/浮動小数点のフォーマット検証と範囲制約 (gt, gte, lt, lte) のチェック                                                         |
+| `directive.ts`         | プレフィックスパターン (文字列または正規表現) のマッチング後、トークン部分を `checkBase()` で再帰的に検証                         |
+| `check-multi-types.ts` | 複数のチェッカーを順に試行し、最初にマッチした結果、またはパス数・オフセットが最大の不一致結果を返す                              |
+| `get-candidate.ts`     | レーベンシュタイン距離を用いたタイプミスの修正候補提示                                                                            |
+
+### 3. トークンシステム
+
+トークンシステムは、位置情報を保持したまま文字列を解析し、正確なエラー位置を報告するための基盤です。
+
+| ファイル                    | 役割                                                                                                                                                 |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `token/token.ts`            | `Token` クラス。値・オフセット・行・列を保持。位置情報付きエラー結果を生成する `unmatched()` メソッドを提供                                          |
+| `token/token-collection.ts` | `TokenCollection` クラス (`Array<Token>` を継承)。設定可能なセパレータで文字列をトークンに分割。ユニーク制約・順序チェック・パターンマッチングに対応 |
+| `token/types.ts`            | トークン値の型定義: `TokenValueScalar` (文字列、RegExp、数値)、`TokenValueArray`                                                                     |
+
+### 4. バリデーター群
+
+Web標準の仕様に基づいた、個別の値検証ロジックを実装しています。
+
+| ディレクトリ | バリデーター                                                                                                                                                                                         |
+| ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `primitive/` | `isFloat`, `isInt`, `isUint`, `isNonZeroUint`, `isQuantity`, `splitUnit`, `range`                                                                                                                    |
+| `whatwg/`    | `checkDateTime` (8種のサブバリデーター), `checkAutoComplete`, `checkMIMEType`, `checkLinkType`, `isAbsURL`, `isCustomElementName`, `isNavigableTargetName`, `isBrowserContextName`, `isItempropName` |
+| `rfc/`       | `isBCP47` (BCP 47 言語タグ検証)                                                                                                                                                                      |
+| `w3c/`       | `checkSerializedPermissionsPolicy` (Permissions Policy 検証)                                                                                                                                         |
+
+## 外部依存パッケージ
+
+| パッケージ        | 用途                                               | 使用箇所                                   |
+| ----------------- | -------------------------------------------------- | ------------------------------------------ |
+| `css-tree`        | CSS値定義構文のレキサーフォークによるマッチング    | `css-syntax.ts`                            |
+| `bcp-47`          | BCP 47 言語タグのパースと検証                      | `rfc/is-bcp-47.ts`, `css-tokenizers.ts`    |
+| `whatwg-mimetype` | WHATWG MIMEタイプのパース                          | `whatwg/check-mime-type.ts`                |
+| `leven`           | タイプミス検出のためのレーベンシュタイン距離計算   | `get-candidate.ts`                         |
+| `debug`           | 名前空間 `@markuplint/types` のデバッグログ        | `debug.ts`                                 |
+| `type-fest`       | 深い不変性のための `ReadonlyDeep` ユーティリティ型 | `check.ts`, `check-base.ts` 他各チェッカー |
+
+## 他パッケージとの連携
+
+```mermaid
+flowchart LR
+    subgraph upstream ["上流パッケージ"]
+        mlSpec["@markuplint/ml-spec"]
+    end
+
+    subgraph pkg ["@markuplint/types"]
+        defs["defs レジストリ"]
+        check["check()"]
+        types["型定義"]
+    end
+
+    subgraph downstream ["下流パッケージ"]
+        rules["@markuplint/rules"]
+    end
+
+    mlSpec -->|"Defs を提供\n(型定義)"| defs
+    mlSpec -->|"Type 共用体を使用\n(属性仕様の記述)"| types
+    rules -->|"check() を呼び出し\n属性値を検証"| check
+```
+
+### 上流: `@markuplint/ml-spec`
+
+`@markuplint/ml-spec` は、要素仕様の中で属性値の制約を表現するために `Type` 共用体と関連する型 (`List`, `Enum`, `Number`, `Directive`, `KeywordDefinedType`) を利用します。また、組み込み定義レジストリを拡張する `Defs` エントリを生成します。
+
+### 下流: `@markuplint/rules`
+
+`@markuplint/rules` は、パース済み HTML ドキュメント中の属性値を検証するために `check(value, type)` を呼び出します。`Result` 型がエラー報告を駆動し、`UnmatchedResult` に含まれるオフセット・行・列・理由・期待値・修正候補の情報を、ルールがリント診断メッセージに変換します。
+
+## ドキュメントマップ
+
+- [型システム](docs/type-system.ja.md) -- 型共用体、Result型、Defsレジストリ、スキーマ生成
+- [チェックパイプライン](docs/check-pipeline.ja.md) -- `check()` から個別チェッカーまでのバリデーションフロー
+- [トークンシステム](docs/token-system.ja.md) -- Token クラス、TokenCollection、パースパターン
+- [バリデーター](docs/validators.ja.md) -- プリミティブ、WHATWG、RFC、W3C バリデーター

package/ARCHITECTURE.md

@@ -0,0 +1,252 @@
+# @markuplint/types
+
+## Overview
+
+`@markuplint/types` is the attribute value type validation system for markuplint. It validates HTML and SVG attribute values against type definitions derived from the HTML Living Standard, CSS specifications, and related web standards.
+
+Given a string value and a type definition, the package determines whether the value conforms to the type and, when it does not, produces a detailed error result including the mismatch position, reason, expected values, and suggested corrections.
+
+## Directory Structure
+
+```
+src/
+├── index.ts                        # Package entry point; re-exports public API
+├── types.ts                        # Core type definitions (Result, Defs, CustomSyntax, etc.)
+├── types.schema.ts                 # Auto-generated types from JSON schema (Type, List, Enum, Number, Directive)
+├── check.ts                        # Primary entry point: check() with built-in defs
+├── check-base.ts                   # Core dispatcher: routes to checkers by type shape
+├── check-multi-types.ts            # Tries multiple checkers, returns best result
+├── match-result.ts                 # Factory functions: matched(), unmatched(), matches()
+├── defs.ts                         # Built-in HTML type definitions registry (Any, URL, DateTime, etc.)
+├── css-defs.ts                     # CSS/SVG type definitions (viewBox, dasharray, etc.)
+├── css-syntax.ts                   # CSS syntax matching via css-tree fork
+├── css-overrides.ts                # Overrides for css-tree built-in syntax (SVG transforms)
+├── css-tokenizers.ts               # Custom tokenizers for css-tree (BCP-47)
+├── keyword-type.ts                 # Keyword type resolution with caching
+├── enum.ts                         # Enum checker (case-insensitive set membership)
+├── list.ts                         # List checker (comma/space-separated token sequences)
+├── number.ts                       # Number checker (int/float with range constraints)
+├── directive.ts                    # Directive checker (prefix pattern + token validation)
+├── get-candidate.ts                # Typo correction via Levenshtein distance
+├── debug.ts                        # Debug logger instance
+├── primitive/                      # Primitive numeric validators
+│   ├── index.ts                    # Re-exports all primitive validators
+│   ├── is-float.ts                 # Floating-point number validation
+│   ├── is-int.ts                   # Signed integer validation
+│   ├── is-uint.ts                  # Unsigned integer validation
+│   ├── is-non-zero-uint.ts         # Non-zero unsigned integer validation
+│   ├── is-quantity.ts              # CSS quantity (number + unit) validation
+│   ├── split-unit.ts               # Splits numeric value from unit suffix
+│   ├── range.ts                    # Numeric range checking utility
+│   └── index.spec.ts               # Tests
+├── token/                          # Position-tracked token system
+│   ├── index.ts                    # Re-exports Token and TokenCollection
+│   ├── token.ts                    # Token class with offset, line, column tracking
+│   ├── token-collection.ts         # TokenCollection: parsed token sequence with validation
+│   ├── types.ts                    # Token value types (scalar, array, regex, number)
+│   └── index.spec.ts               # Tests
+├── whatwg/                          # WHATWG HTML Standard validators
+│   ├── check-autocomplete.ts       # Autocomplete attribute validation
+│   ├── check-datetime/             # DateTime microsyntax validators (date, time, month, etc.)
+│   │   ├── index.ts                # Dispatcher for all datetime formats
+│   │   ├── date-string.ts          # YYYY-MM-DD
+│   │   ├── time-string.ts          # HH:MM:SS
+│   │   ├── month-string.ts         # YYYY-MM
+│   │   ├── week-string.ts          # YYYY-Www
+│   │   ├── year-string.ts          # YYYY
+│   │   ├── yearless-date-string.ts # MM-DD
+│   │   ├── duration-string.ts      # Duration format
+│   │   ├── global-date-and-time-string.ts
+│   │   ├── local-date-and-time-string.ts
+│   │   ├── time-zone-offset-string.ts
+│   │   ├── datetime-tokens.ts      # Shared token patterns
+│   │   └── index.spec.ts           # Tests
+│   ├── check-link-type.ts          # Link type validation (rel attribute)
+│   ├── check-mime-type.ts          # MIME type validation
+│   ├── is-abs-url.ts               # Absolute URL check
+│   ├── is-browser-context-name.ts  # Browsing context name check (deprecated)
+│   ├── is-custom-element-name.ts   # Custom element name check
+│   ├── is-itemprop-name.ts         # Itemprop name check
+│   └── is-navigable-target-name.ts # Navigable target name check
+├── rfc/                             # RFC-based validators
+│   ├── is-bcp-47.ts                # BCP 47 language tag validation
+│   └── is-bcp-47.spec.ts           # Tests
+└── w3c/                             # W3C specification validators
+    ├── check-serialized-permissions-policy.ts  # Permissions Policy validation
+    └── check-serialized-permissions-policy.spec.ts  # Tests
+```
+
+## Architecture Diagram
+
+```mermaid
+flowchart TD
+    subgraph entry ["Entry Point"]
+        check["check(value, type)"]
+    end
+
+    subgraph dispatch ["Core Dispatcher"]
+        checkBase["checkBase(value, type, defs)"]
+        isKeyword{"isKeyword?"}
+        isList{"isList?"}
+        isEnum{"isEnum?"}
+        isNumber{"isNumber?"}
+        isDirective{"isDirective?"}
+    end
+
+    subgraph checkers ["Individual Checkers"]
+        checkKeywordType["checkKeywordType()"]
+        checkListFn["checkList()"]
+        checkEnumFn["checkEnum()"]
+        checkNumberFn["checkNumber()"]
+        checkDirectiveFn["checkDirective()"]
+    end
+
+    subgraph resolution ["Keyword Resolution"]
+        defsRegistry["defs + cssDefs registry"]
+        cssSyntaxMatch["cssSyntaxMatch()"]
+        customSyntax["CustomSyntax.is()"]
+    end
+
+    subgraph result ["Result"]
+        matched["MatchedResult"]
+        unmatched["UnmatchedResult"]
+    end
+
+    check --> checkBase
+    checkBase --> isKeyword
+    isKeyword -->|string| checkKeywordType
+    isKeyword -->|object| isList
+    isList -->|separator| checkListFn
+    isList -->|no| isEnum
+    isEnum -->|enum| checkEnumFn
+    isEnum -->|no| isNumber
+    isNumber -->|float/integer| checkNumberFn
+    isNumber -->|no| isDirective
+    isDirective -->|directive| checkDirectiveFn
+
+    checkKeywordType --> defsRegistry
+    defsRegistry -->|CustomCssSyntax| cssSyntaxMatch
+    defsRegistry -->|CustomSyntax| customSyntax
+    defsRegistry -->|not found| cssSyntaxMatch
+
+    checkListFn -->|each token| checkBase
+    checkDirectiveFn -->|token part| checkBase
+
+    cssSyntaxMatch --> matched
+    cssSyntaxMatch --> unmatched
+    customSyntax --> matched
+    customSyntax --> unmatched
+    checkEnumFn --> matched
+    checkEnumFn --> unmatched
+    checkNumberFn --> matched
+    checkNumberFn --> unmatched
+```
+
+## Core Components
+
+### 1. Type System
+
+The type system defines what kinds of attribute values can be expressed and how validation results are represented.
+
+| File              | Purpose                                                                                                        |
+| ----------------- | -------------------------------------------------------------------------------------------------------------- |
+| `types.ts`        | Core types: `Result`, `MatchedResult`, `UnmatchedResult`, `Defs`, `CustomSyntax`, `CustomCssSyntax`            |
+| `types.schema.ts` | Auto-generated union type `Type` and its variants: `KeywordDefinedType`, `List`, `Enum`, `Number`, `Directive` |
+| `match-result.ts` | Factory functions `matched()`, `unmatched()`, and the `matches()` wrapper                                      |
+| `defs.ts`         | Built-in HTML definitions registry (30+ types: `Any`, `URL`, `DateTime`, `DOMID`, `BCP47`, etc.)               |
+| `css-defs.ts`     | CSS/SVG definitions (25+ types: `<view-box>`, `<preserve-aspect-ratio>`, `<dasharray>`, etc.)                  |
+
+The `Type` union is the central discriminated union:
+
+- **String** (keyword) -- e.g., `"URL"`, `"<color>"`, `"DateTime"`
+- **Object with `separator`** (list) -- space-separated or comma-separated token sequences
+- **Object with `enum`** (enum) -- fixed set of allowed string values
+- **Object with `type: "float" | "integer"`** (number) -- numeric with range constraints
+- **Object with `directive`** (directive) -- prefix pattern followed by a typed token
+
+### 2. Check Pipeline
+
+The validation pipeline routes a value through the correct checker based on the type definition's shape.
+
+| File                   | Purpose                                                                                                                                 |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| `check.ts`             | Public `check()` function. Merges `defs` and `cssDefs`, delegates to `checkBase()`                                                      |
+| `check-base.ts`        | Dispatcher. Inspects type shape via `isKeyword()`, `isList()`, `isEnum()`, `isNumber()`, `isDirective()` and calls the matching checker |
+| `keyword-type.ts`      | Resolves keyword types: looks up in `Defs` registry, falls back to `cssSyntaxMatch()`. Caches results                                   |
+| `css-syntax.ts`        | Matches values against CSS value definition syntax using a `css-tree` fork with custom types and tokenizers                             |
+| `enum.ts`              | Validates against a set of allowed string values (case-insensitive by default)                                                          |
+| `list.ts`              | Splits value into tokens by separator, validates each token recursively via `checkBase()`                                               |
+| `number.ts`            | Validates integer/float format and checks range constraints (gt, gte, lt, lte)                                                          |
+| `directive.ts`         | Matches prefix patterns (string or regex), extracts token portion, validates recursively via `checkBase()`                              |
+| `check-multi-types.ts` | Tries multiple checkers, returns first match or best unmatched result                                                                   |
+| `get-candidate.ts`     | Suggests corrections for typos using Levenshtein distance                                                                               |
+
+### 3. Token System
+
+The token system provides position-tracked string parsing for generating precise error locations.
+
+| File                        | Purpose                                                                                                                                                        |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `token/token.ts`            | `Token` class. Tracks value, offset, line, column. Provides `unmatched()` for position-aware error results                                                     |
+| `token/token-collection.ts` | `TokenCollection` class (extends `Array<Token>`). Parses strings into tokens with configurable separators. Supports uniqueness, ordering, and pattern matching |
+| `token/types.ts`            | Token value types for matching: `TokenValueScalar` (string, RegExp, number), `TokenValueArray`                                                                 |
+
+### 4. Validators
+
+Domain-specific validators implementing checks for values defined in web standards.
+
+| Directory    | Validators                                                                                                                                                                                      |
+| ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `primitive/` | `isFloat`, `isInt`, `isUint`, `isNonZeroUint`, `isQuantity`, `splitUnit`, `range`                                                                                                               |
+| `whatwg/`    | `checkDateTime` (8 sub-validators), `checkAutoComplete`, `checkMIMEType`, `checkLinkType`, `isAbsURL`, `isCustomElementName`, `isNavigableTargetName`, `isBrowserContextName`, `isItempropName` |
+| `rfc/`       | `isBCP47` (BCP 47 language tag validation)                                                                                                                                                      |
+| `w3c/`       | `checkSerializedPermissionsPolicy` (Permissions Policy)                                                                                                                                         |
+
+## External Dependencies
+
+| Dependency        | Purpose                                             | Where Used                                |
+| ----------------- | --------------------------------------------------- | ----------------------------------------- |
+| `css-tree`        | CSS value definition syntax matching via lexer fork | `css-syntax.ts`                           |
+| `bcp-47`          | BCP 47 language tag parsing and validation          | `rfc/is-bcp-47.ts`, `css-tokenizers.ts`   |
+| `whatwg-mimetype` | WHATWG MIME type parsing                            | `whatwg/check-mime-type.ts`               |
+| `leven`           | Levenshtein distance for typo detection             | `get-candidate.ts`                        |
+| `debug`           | Debug logging with namespace `@markuplint/types`    | `debug.ts`                                |
+| `type-fest`       | `ReadonlyDeep` utility type for deep immutability   | `check.ts`, `check-base.ts`, and checkers |
+
+## Integration Points
+
+```mermaid
+flowchart LR
+    subgraph upstream ["Upstream"]
+        mlSpec["@markuplint/ml-spec"]
+    end
+
+    subgraph pkg ["@markuplint/types"]
+        defs["defs registry"]
+        check["check()"]
+        types["Type definitions"]
+    end
+
+    subgraph downstream ["Downstream"]
+        rules["@markuplint/rules"]
+    end
+
+    mlSpec -->|"provides Defs\n(type definitions)"| defs
+    mlSpec -->|"uses Type union\nfor attribute specs"| types
+    rules -->|"calls check()\nto validate attribute values"| check
+```
+
+### Upstream: `@markuplint/ml-spec`
+
+`@markuplint/ml-spec` consumes the `Type` union and related types (`List`, `Enum`, `Number`, `Directive`, `KeywordDefinedType`) to describe attribute value constraints in element specifications. It also produces `Defs` entries that extend the built-in definitions registry.
+
+### Downstream: `@markuplint/rules`
+
+`@markuplint/rules` calls `check(value, type)` to validate attribute values found in parsed HTML documents. The `Result` type drives error reporting: an `UnmatchedResult` provides the offset, line, column, reason, expected values, and candidate corrections that rules translate into lint diagnostics.
+
+## Documentation Map
+
+- [Type System](docs/type-system.md) -- Type unions, Result types, Defs registry, schema generation
+- [Check Pipeline](docs/check-pipeline.md) -- Validation flow from `check()` through individual checkers
+- [Token System](docs/token-system.md) -- Token class, TokenCollection, parse patterns
+- [Validators](docs/validators.md) -- Primitive, WHATWG, RFC, W3C validators

package/CHANGELOG.md

@@ -3,23 +3,25 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
-# [4.8.0](https://github.com/markuplint/markuplint/compare/@markuplint/types@4.7.7...@markuplint/types@4.8.0) (2025-08-24)
-
+## [4.8.2](https://github.com/markuplint/markuplint/compare/@markuplint/types@4.8.1...@markuplint/types@4.8.2) (2026-02-10)
 
-### Bug Fixes
-
-* **types:** adjust type checking for css-tree update ([7fff913](https://github.com/markuplint/markuplint/commit/7fff913f4630eab6017861934142636d3c267336))
-* **types:** fix bug that spaces are invalid even if separator is 'space' when disallowToSurroundBySpaces is enabled ([3b81c3b](https://github.com/markuplint/markuplint/commit/3b81c3b525cd406275936236f8b793efed8864d7))
+**Note:** Version bump only for package @markuplint/types
 
+## [4.8.1](https://github.com/markuplint/markuplint/compare/@markuplint/types@4.8.0...@markuplint/types@4.8.1) (2025-11-05)
 
-### Features
+**Note:** Version bump only for package @markuplint/types
 
-* **types:** add link type definitions for specific HTML elements ([7199a8e](https://github.com/markuplint/markuplint/commit/7199a8eb4eaf334855ba78064c4340e040d8614c))
-* **types:** add link type validation for HTML elements ([ed7cc6c](https://github.com/markuplint/markuplint/commit/ed7cc6c2b703e14b8572087eb07c63a97d864187))
+# [4.8.0](https://github.com/markuplint/markuplint/compare/@markuplint/types@4.7.7...@markuplint/types@4.8.0) (2025-08-24)
 
+### Bug Fixes
 
+- **types:** adjust type checking for css-tree update ([7fff913](https://github.com/markuplint/markuplint/commit/7fff913f4630eab6017861934142636d3c267336))
+- **types:** fix bug that spaces are invalid even if separator is 'space' when disallowToSurroundBySpaces is enabled ([3b81c3b](https://github.com/markuplint/markuplint/commit/3b81c3b525cd406275936236f8b793efed8864d7))
 
+### Features
 
+- **types:** add link type definitions for specific HTML elements ([7199a8e](https://github.com/markuplint/markuplint/commit/7199a8eb4eaf334855ba78064c4340e040d8614c))
+- **types:** add link type validation for HTML elements ([ed7cc6c](https://github.com/markuplint/markuplint/commit/ed7cc6c2b703e14b8572087eb07c63a97d864187))
 
 ## [4.7.7](https://github.com/markuplint/markuplint/compare/@markuplint/types@4.7.6...@markuplint/types@4.7.7) (2025-08-13)
 

package/README.md

@@ -31,6 +31,41 @@ check('2020-02-30', 'DateTime');
 // }
 ```
 
+### `checkBase`
+
+Validates a value against a type definition object (enum, list, number, directive, or keyword type).
+
+```ts
+import { checkBase } from '@markuplint/types';
+
+checkBase('hello', { enum: ['hello', 'world'] }, {});
+// => { matched: true }
+```
+
+### `isCustomElementName`
+
+Checks whether a string is a valid custom element name according to the WHATWG specification.
+
+```ts
+import { isCustomElementName } from '@markuplint/types';
+
+isCustomElementName()('my-element'); // => true
+isCustomElementName()('div'); // => false
+```
+
+### Type Exports
+
+The package also exports the following types:
+
+| Type                  | Description                                                |
+| --------------------- | ---------------------------------------------------------- |
+| `Result`              | Union type of `MatchedResult` and `UnmatchedResult`        |
+| `MatchedResult`       | Represents a successful match (`{ matched: true }`)        |
+| `UnmatchedResult`     | Represents a failed match with location and reason details |
+| `Type`                | Union of all type definition shapes (enum, list, etc.)     |
+| `Defs`                | Registry mapping type identifiers to their definitions     |
+| `CustomSyntaxChecker` | Factory function type for creating value checkers          |
+
 ## Type Identifiers
 
 | Identifier                         | Use on                                      | Spec                                                                                                                                                               | Supported |
@@ -54,8 +89,8 @@ check('2020-02-30', 'DateTime');
 | `HashName`                         | `img[usemap]`                               | [WHATWG](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-hash-name-reference)                                                               | ✅        |
 | `OneCodePointChar`                 | The `accesskey` attribute (as list)         | [WHATWG](https://html.spec.whatwg.org/multipage/interaction.html#the-accesskey-attribute)                                                                          | ✅        |
 | `CustomElementName`                | The `is` attribute                          | [WHATWG](https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name)                                                                    | ✅        |
-| ~~`BrowsingContextName`~~          | Use `NavigableTargetName` instead.          | **Obsolated**                                                                                                                                                      | ✅        |
-| ~~`BrowsingContextNameOrKeyword`~~ | Use `NavigableTargetNameOrKeyword` instead. | **Obsolated**                                                                                                                                                      | ✅        |
+| ~~`BrowsingContextName`~~          | Use `NavigableTargetName` instead.          | **Obsoleted**                                                                                                                                                      | ✅        |
+| ~~`BrowsingContextNameOrKeyword`~~ | Use `NavigableTargetNameOrKeyword` instead. | **Obsoleted**                                                                                                                                                      | ✅        |
 | `NavigableTargetName`              | `iframe[name]` and more                     | [WHATWG](https://html.spec.whatwg.org/multipage/document-sequences.html#valid-navigable-target-name)                                                               | ✅        |
 | `NavigableTargetNameOrKeyword`     | `a[target]` and more                        | [WHATWG](https://html.spec.whatwg.org/multipage/document-sequences.html#valid-navigable-target-name-or-keyword)                                                    | ✅        |
 | `HTTPSchemaURL`                    | `a[ping]` (as list) and more                | [WHATWG](https://html.spec.whatwg.org/multipage/links.html#ping)                                                                                                   | ✅        |