# バリデータ
## 概要
`@markuplint/types` パッケージは、HTML属性値を検証するための階層的なバリデーションシステムを提供しています。バリデータとは、与えられた文字列がWeb標準（WHATWG, W3C, RFC）やプリミティブ型の定義に準拠しているかどうかを検査する関数です。
### 型システムにおける位置づけ
バリデータは型チェックパイプラインの中核を担っています。markuplintが属性値を評価する際、以下の手順で処理が進みます。
1. スキーマから属性の期待される型を解決する（例: `DateTime`、`BCP47`、`Uint`）
2. `defs` レジストリ（`src/defs.ts`）で該当するバリデータを参照する
3. バリデータを呼び出し、結果として `MatchedResult`（適合）または `UnmatchedResult`（不適合、詳細なエラー情報付き）を得る
### バリデータのパターン
バリデータには2つの主要なパターンがあります。
- **`FormattedPrimitiveTypeCreator`** -- 真偽値を返す述語関数 `(value: string) => boolean` を生成するファクトリ。`isInt` や `isAbsURL`、`isCustomElementName` のようなシンプルな検証に使われます。`defs.ts` に登録する際は `matches()` ヘルパーでラップします。
- **`CustomSyntaxChecker`** -- `(value: string) => Result` を返すファクトリ。エラーの位置・理由・修正候補まで含めた詳細な結果を返します。`checkDateTime` や `checkAutoComplete`、`checkSerializedPermissionsPolicy` のような複雑なバリデータに使われます。
### カテゴリ
バリデータは、準拠する仕様に基づいて4つのカテゴリに分類されています。
| カテゴリ | ディレクトリ | 説明 |
| --------- | ---------------- | ---------------------------------------------------- |
| Primitive | `src/primitive/` | 基本的な数値・文字列フォーマットの検証 |
| WHATWG | `src/whatwg/` | HTML Living Standardで定義されたマイクロシンタックス |
| RFC | `src/rfc/` | IETFのRFCで定義されたフォーマット |
| W3C | `src/w3c/` | W3C仕様で定義されたフォーマット |
---
## プリミティブバリデータ
プリミティブバリデータは、数値や単位付き値の基本的なフォーマット検証を行います。単体で使用されるだけでなく、上位のバリデータの構成要素としても利用されます。
**ソース:** `src/primitive/index.ts`
| 関数 | ファイル | 説明 | パラメータ | 戻り値 |
| --------------- | ------------------------------- | ------------------------- | ----------------------------------------------------------------------------- | ------------------------------- |
| `isInt` | `primitive/is-int.ts` | 符号付き整数の検証 | `value: string` | `boolean` |
| `isFloat` | `primitive/is-float.ts` | 浮動小数点数の検証 | `value: string` | `boolean` |
| `isUint` | `primitive/is-uint.ts` | 非負整数の検証 | `value: string`, `options?: { gt?: number }` | `boolean` |
| `isNonZeroUint` | `primitive/is-non-zero-uint.ts` | 0より大きい非負整数の検証 | `value: string` | `boolean` |
| `isQuantity` | `primitive/is-quantity.ts` | 数値＋単位の検証 | `value: string`, `units: string[]`, `numberType?: 'int' \| 'uint' \| 'float'` | `boolean` |
| `range` | `primitive/range.ts` | 数値範囲の検証 | `value: string`, `from: number`, `to: number` | `boolean` |
| `splitUnit` | `primitive/split-unit.ts` | 数値部と単位部への分割 | `value: string` | `{ num: string, unit: string }` |
### 各バリデータの検証ロジック
**`isInt`** -- 正規表現 `/^-?\d+$/` で、省略可能なマイナス記号に続く1桁以上の数字にマッチするかを判定します。WHATWGの[符号付き整数](https://html.spec.whatwg.org/dev/common-microsyntaxes.html#signed-integers)マイクロシンタックスに対応しています。
```typescript
// src/primitive/is-int.ts
export function isInt(value: string) {
return /^-?\d+$/.test(value);
}
```
**`isFloat`** -- 値をトリムした上で `Number.parseFloat()` で解析し、結果が有限であるかを確認します。科学的記数法を含む標準的な浮動小数点表記に対応します。WHATWGの[浮動小数点数](https://html.spec.whatwg.org/dev/common-microsyntaxes.html#floating-point-numbers)マイクロシンタックスに基づいた緩やかな実装です。`Number.parseFloat()` はWHATWGの厳密な文法よりも寛容であり、先頭ドット（`".5"` など）や末尾の非数値文字を許容する点に注意してください。
```typescript
// src/primitive/is-float.ts
export function isFloat(value: string) {
return value === value.trim() && Number.isFinite(Number.parseFloat(value));
}
```
**`isUint`** -- `/^\d+$/` で非負整数にマッチさせます。オプションで `gt` 制約を指定でき、その場合はパースした値が指定値より厳密に大きいことを要求します。WHATWGの[非負整数](https://html.spec.whatwg.org/dev/common-microsyntaxes.html#non-negative-integers)マイクロシンタックスに対応します。
**`isNonZeroUint`** -- `/^\d+$/` にマッチすることに加え、ゼロのみで構成される文字列（`/^0+$/`）を拒否します。つまり正の整数であることを保証します。
**`isQuantity`** -- `splitUnit` を使って数値部と単位部に分割した後、単位が許可リストに含まれているか（大文字小文字を区別しない）を確認し、数値部を指定された `numberType`（`'int'`、`'uint'`、`'float'`）に従って検証します。`"10px"` や `"1.5em"` のような値の検証に使います。
**`range`** -- 値を浮動小数点数としてパースし、`[from, to]` の範囲内（両端を含む）に収まるかを判定します。数値にパースできない場合は `false` を返します。
**`splitUnit`** -- 正規表現 `/(^-?\.\d+|^-?\d+(?:\.\d+(?:e[+-]\d+)?)?)([a-z]+$)/i` を使い、`"10px"` を `{ num: "10", unit: "px" }` のように分割します。単位が見つからない場合は `{ num: value, unit: "" }` を返します。
---
## WHATWGバリデータ
WHATWGバリデータは、[HTML Living Standard](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html)で定義されたマイクロシンタックスを実装しています。
### DateTimeサブシステム
DateTimeサブシステムは、WHATWG仕様が定義するすべての日時フォーマットを検証します。12個の個別フォーマットチェッカーで構成されており、共通のトークン検証レイヤーを共有する最も複雑なバリデータ群です。
**エントリポイント:** `src/whatwg/check-datetime/index.ts`
トップレベルの `checkDateTime` 関数は、`checkMultiTypes` を使ってすべてのフォーマットを試行し、最も適合度の高い結果を返します。
```typescript
// src/whatwg/check-datetime/index.ts
const checks = [
checkDateString(),
checkTimeString(),
checkMonthString(),
checkYearlessDateString(),
checkLocalDateAndTimeString(),
checkNormalizedLocalDateAndTimeString(),
checkTimeZoneOffsetString(),
checkGlobalDateAndTimeString(),
checkWeekString(),
checkYearString(),
checkDurationISO8601LikeString(),
checkDurationComponentListString(),
];
export const checkDateTime: CustomSyntaxChecker = () => value => {
return checkMultiTypes(value, checks);
};
```
#### 日時フォーマットチェッカー一覧
| 関数 | ファイル | フォーマット | 例 | 仕様参照 |
| --------------------------------------- | -------------------------------- | --------------------------------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `checkDateString` | `date-string.ts` | `YYYY-MM-DD` | `2024-01-15` | [日付](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#dates) |
| `checkMonthString` | `month-string.ts` | `YYYY-MM` | `2024-01` | [月](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-month-string) |
| `checkWeekString` | `week-string.ts` | `YYYY-Www` | `2024-W03` | [週](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#weeks) |
| `checkTimeString` | `time-string.ts` | `HH:MM[:SS[.sss]]` | `14:30:00` | [時刻](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#times) |
| `checkYearlessDateString` | `yearless-date-string.ts` | `MM-DD` | `01-15` | [年なし日付](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#yearless-dates) |
| `checkYearString` | `year-string.ts` | `YYYY`（4桁以上、0より大きい） | `2024` | [共通マイクロシンタックス](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html) |
| `checkLocalDateAndTimeString` | `local-date-and-time-string.ts` | `YYYY-MM-DDThh:mm[:ss[.sss]]` | `2024-01-15T14:30` | [ローカル日時](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-local-date-and-time-string) |
| `checkNormalizedLocalDateAndTimeString` | `local-date-and-time-string.ts` | 正規化されたローカル日時 | `2024-01-15T14:30` | [正規化ローカル日時](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#valid-normalised-local-date-and-time-string) |
| `checkGlobalDateAndTimeString` | `global-date-and-time-string.ts` | 日付＋時刻＋タイムゾーン | `2024-01-15T14:30:00Z` | [グローバル日時](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#global-dates-and-times) |
| `checkTimeZoneOffsetString` | `time-zone-offset-string.ts` | `Z` または `+HH:MM` / `-HH:MM` | `+09:00` | [タイムゾーン](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#time-zones) |
| `checkDurationISO8601LikeString` | `duration-string.ts` | ISO 8601形式（`PnDTnHnMnS`） | `PT1H30M` | [期間](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#durations) |
| `checkDurationComponentListString` | `duration-string.ts` | コンポーネントリスト形式（`1h 30m 5s`） | `1h 30m 5s` | [期間](https://html.spec.whatwg.org/multipage/common-microsyntaxes.html#durations) |
#### 共有トークン定義
すべての日時チェッカーは、`datetime-tokens.ts` で定義された共通のトークン検証レイヤーを共有しています。`datetimeTokenCheck` オブジェクトが、各日時コンポーネントに対応する再利用可能な `TokenEachCheck` 関数を提供します。
```mermaid
graph TD
A[checkDateTime] --> B[checkMultiTypes]
B --> C[checkDateString]
B --> D[checkTimeString]
B --> E[checkMonthString]
B --> F[checkYearlessDateString]
B --> G[checkLocalDateAndTimeString]
B --> H[checkNormalizedLocalDateAndTimeString]
B --> I[checkGlobalDateAndTimeString]
B --> J[checkTimeZoneOffsetString]
B --> K[checkWeekString]
B --> L[checkYearString]
B --> M[checkDurationISO8601LikeString]
B --> N[checkDurationComponentListString]
C --> O[datetimeTokenCheck]
D --> O
E --> O
F --> O
G --> O
H --> O
I --> O
J --> O
K --> O
L --> O
M --> O
N --> O
O --> P[year]
O --> Q[month]
O --> R[date]
O --> S[hour]
O --> T[minute]
O --> U[second]
O --> V[secondFractionalPart]
O --> W[week]
O --> X[hyphen / colon / separators]
```
共有トークンチェックの一覧:
| トークンチェック | 検証対象 | 制約 |
| ---------------------------------- | ---------------------- | -------------------------------- |
| `year` | 年 | 4桁以上のASCII数字、値 > 0 |
| `month` | 月 | 2桁、1--12の範囲 |
| `date` | 日 | 2桁、1--maxday（うるう年を考慮） |
| `hour` | 時 | 2桁、0--23の範囲 |
| `minute` | 分 | 2桁、0--59の範囲 |
| `second` | 秒 | 2桁、0--59の範囲 |
| `secondFractionalPart` | 秒の小数部 | 1--3桁のASCII数字 |
| `week` | ISO週番号 | 2桁、1--maxweek（年による） |
| `hyphen` | `-` セパレータ | U+002D固定 |
| `colon` | `:` セパレータ | U+003A固定 |
| `colonOrEnd` | `:` または入力の終わり | コロンは省略可 |
| `decimalPointOrEnd` | `.` または入力の終わり | ピリオドは省略可 |
| `localDateTimeSeparator` | `T` またはスペース | 日付と時刻の境界 |
| `normalizedlocalDateTimeSeparator` | `T` のみ | 正規化形式での厳密な区切り |
| `plusOrMinusSign` | `+` または `-` | タイムゾーンの符号 |
| `weekSign` | `W` | 週文字列のマーカー |
| `extra` | 末尾の余分な内容 | 空でなければ拒否 |
`datetimeTokenCheck` オブジェクトは、検証の過程で `_year` と `_month` をミュータブルな状態として保持します。これにより `date` チェッカーが、対象の年月に対する正確な最大日数を計算できます（うるう年の判定を含む）。
### オートコンプリートバリデータ
**ソース:** `src/whatwg/check-autocomplete.ts`
[WHATWGオートフィル仕様](https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#attr-fe-autocomplete)に基づいて `autocomplete` 属性値を検証します。
トークンベースのアプローチを採用しており、属性値をスペース区切りの順序付きトークン集合として解析します。認識されるトークンは以下のとおりです。
- **キーワード:** `on`、`off`（単独使用、他のトークンとの共存不可）
- **名前付きグループ:** `section-` で始まるトークン（省略可能な接頭辞）
- **住所区分:** `shipping`、`billing`（省略可能）
- **連絡手段トークン:** `home`、`work`、`mobile`、`fax`、`pager`（省略可能、後に連絡先フィールド名が必須）
- **オートフィルフィールド名:** `name`、`given-name`、`postal-code`、`cc-number` など（44種類）
- **連絡先フィールド名:** `tel`、`tel-country-code`、`email`、`impp` など（10種類）
- **WebAuthn:** `webauthn`（省略可能な末尾トークン）
WHATWGが定義する順序制約を適用します: `[section-*] [shipping|billing] [home|work|...] <フィールド名> [webauthn]`。重複トークンや不正な順序は、タイプミス候補を含む詳細なエラー結果を生成します。
### リンクタイプバリデータ
**ソース:** `src/whatwg/check-link-type.ts`
`rel` 属性のリンクタイプ値を、[WHATWGリンクタイプレジストリ](https://html.spec.whatwg.org/multipage/links.html#linkTypes)と[Microformatsのexisting-rel-values](https://microformats.org/wiki/existing-rel-values)レジストリに照らし合わせて検証します。
要素のコンテキストに応じたパラメータを受け取ります。
| オプション | コンテキスト | 説明 |
| ----------------- | ---------------------- | ------------------------------------------- |
| `el: 'link'` | `` 内の `` | link要素で許可されるすべてのリンクタイプ |
| `el: 'body link'` | `` 内の `` | `body-ok` フラグのあるリンクタイプのみ |
| `el: 'a, area'` | ``、`` | アンカー/エリア要素で許可されるリンクタイプ |
| `el: 'form'` | `