アクセシビリティ検査エンジンのルールを、合格・不合格・判定不能で返すよう作る

## lintとテストを、後片付けではなく変更の一部として通す フォーマット、lint、テスト、ドキュメント、コミット規約を、実装後の後片付けではなく変更そのものの一部として扱います。 ### 必須チェック - コミット前に、リポジトリ指定のフォーマッターとリンターを実行します。 - 完了前に全テストスイートを実行し、動作変更にはユニットテストと統合テストの両方を用意します。 - 実行時の動作に影響し得ない変更に限り、文書化された例外に従います。 - 未解決の作業は無関係な変更に紛れ込ませず、プロジェクトの課題トラッカーで管理します。 - 一時的なログ出力やローカルのデバッグ設定をコミットしません。 ### コード規約 - 正常系を追いやすく保つため、エラーと境界条件を早い段階で処理します。 - 既定のexport配置、命名規則、import形式に従います。 - ファイル名とルール識別子に一貫性を持たせ、関数、真偽値、定数をプロジェクト規約に従って区別します。 - 変数は最初に使う箇所の近くで宣言します。 - exportするAPI、引数、戻り値、複雑なロジックを文書化します。 - 対象を絞った機能追加や修正とリファクタリングを分けます。 ## 仮想ノードと実DOMを使い分け、依存の向きを一方通行に保つ 仮想ツリーの抽象化と実DOMノードのどちらを使うかを意図的に選びます。抽象化はキャッシュ済みの属性やプロパティを効率よく扱えますが、ブラウザーAPIとレイアウト動作には実DOMが必要です。 ### ノードの選択 - 属性へのアクセス、キャッシュ済みプロパティ、ツリー走査、セレクター処理には仮想ノードを優先します。 - レイアウト、ジオメトリ、ルート検索、ブラウザーが算出する動作、その他のネイティブAPIには実DOMノードを使います。 - 曖昧な入力は、文書化された1つの変換境界で解決します。 - 仮想ノードへの依存に明確なAPI上または性能上の利点がない限り、汎用ユーティリティの入出力には実DOMを使います。 - 変換ロジックを個々のルールに分散させません。 ### 依存関係の方向 - 標準定義は実行時importを持たない純粋なデータとして保ちます。 - 低レベルのユーティリティは、明示的なパスを通じて、さらに低レベルの基盤コードと標準データだけに依存させます。 - サードパーティ製モジュールのimportは、指定されたアダプターレイヤーに集約します。 - 共有ドメインヘルパーから低レベルのユーティリティを利用することは認めますが、逆方向の依存は決して認めません。 - 高レベルのチェックとルールは、循環を作らずに下位レイヤーを組み合わせられるようにします。 - lintまたはビルドルールを使い、これらの境界を機械的に強制します。 ## 合格・不合格・判定不能で返し、メッセージはメタデータに置く 利用側が適合、違反、証拠不足を区別できるよう、結果の契約を明示します。 ### チェック結果 - テスト対象の条件を満たす場合は`pass`を返します。 - テスト対象の条件に違反する場合は`fail`を返します。 - エンジンが結果を確実に判定できない場合は`incomplete`を返します。 - メッセージテンプレートと`incomplete`になった理由の説明に使う構造化データを添付します。 - 二値の回答を出すためだけに、不確実な状態を`pass`または`fail`へ無理に割り当てません。 ### ルール定義 - 明示的な`all`、`any`、`none`グループでチェックを組み合わせます。 - セレクターと、任意で追加できるマッチャーを使って候補要素の範囲を定めます。 - 影響度は、プロジェクトで宣言された重大度の値だけに制限します。 - HTMLとARIAの定義はチェック内にリストをハードコードせず、一元管理された標準データから読み取ります。 ### ユーザー向けメッセージ - メッセージは実装コードではなく、ルールまたはチェックのメタデータに保持します。 - 値がチェック結果から渡される、名前付きデータプレースホルダーを使います。 - 文法上必要な場合は単数形と複数形を用意します。 - 原文メッセージを変更するたびにローカライズテンプレートを更新します。 ## 色のコントラストとroleの判定は、特に気をつけて見直す アクセシビリティの結果には、不完全なブラウザー情報や急速に変化する標準に依存するものがあります。この領域では、保守的な結果と対象を絞ったレビューが必要です。 ### 色と可視性 - 対応する色形式、不透明度、合成、スタッキングコンテキスト、テキスト効果を考慮します。 - 実効的な背景色またはコントラストを判定できない場合は`incomplete`を返します。 - CSSの可視性だけに依存せず、スクリーンリーダーに対する可視性を意味に基づいて評価します。 - 非表示状態を表す属性、合成ツリー、Shadow DOMの境界を対象に含めます。 ### セマンティック標準 - roleと属性の検証を、現行のアクセシビリティ仕様と同期させます。 - 暗黙的なroleと明示的なroleを別々に解決します。 - すべてのルールが同じ正本を使うよう、一元管理されたroleと属性の定義を参照します。 - 仕様更新と、過去に誤分類されたマークアップに対する回帰ケースを追加します。 - 多数のルールで結果が変わり得る変更には、対象を絞ったレビューを必須とします。 ## Shadow DOMも含む、実物に近いページでルールをテストする 実装とテストの担当範囲を明確に保てるよう、ユニットテストのツリーにソース構造を反映します。 ### ユニットテストとチェックテスト - プロジェクトが提供する標準のチェックコンテキストまたはテストハーネスを使います。 - 共有fixtureと仮想ツリーがハーネスによってすでにクリアされている場合は、テストが所有する状態だけをリセットします。 - 添付するメッセージデータも含め、`pass`、`fail`、`incomplete`の結果をテストします。 - 広範な統合テストを追加する前に、境界条件に対象を絞ったケースを追加します。 ### 統合テスト - 各ルールのfixtureに、構造化された期待結果を対応付けます。 - frame用の入れ子セレクターを含め、エンジンの正規セレクター表現を使います。 - ドキュメントレベルの動作を断片で表せない場合は、完全なHTMLページを使います。 - 関連するすべてのルールまたはチェックに、openなShadow DOMのケースを追加します。 - 変更が仮想ツリー評価に影響する場合は、仮想ルールのカバレッジを更新します。 - 反復作業中は対象を絞ったテストを実行し、引き渡し前には正本となる全テストスイートを実行します。 ## 翻訳用テンプレートは、メッセージと同じコミットで作り直す 生成されたリリースバンドルと、リポジトリが意図的に追跡する生成済みソース成果物を区別します。 ### 成果物ポリシー - バンドル済みまたはminify済みのリリース出力を直接編集しません。 - 追跡対象のテンプレートやソース成果物は、承認済みのビルドを通じて再生成します。 - 生成元のメッセージと同じ変更で、生成されたローカライズテンプレートをコミットします。 - 同期が必要なソースと生成物の更新を別々のコミットに分けません。 - ignore対象の公開用バンドルを通常の機能コミットに含めません。 ### 検証 - 生成された差分を確認し、想定外のメッセージ、ロケール、ルールの変更がないか調べます。 - 新しい各プレースホルダーが、それを生成するチェックデータに存在することを確認します。 - メッセージ変更後にローカライズとビルドの検証を実行します。 - どの成果物が生成物で、どれが追跡対象で、どれがリリース専用かを文書化します。 ## 変更履歴とAPIドキュメントを更新し、互換性を壊さない 各変更の範囲を絞り、その公開上の影響をレビュー担当者と利用者が確認できるようにします。 ### 変更内容の文書化 - ルールを追加する場合、または大きく変更する場合は、変更履歴を更新します。 - 公開インターフェースを変更する場合は、APIドキュメントと型定義を同時に更新します。 - リポジトリ指定のconventional commit形式を使い、簡潔な件名と本文中の変更理由を記載します。 - 対応済みの課題は、対応するfooterまたはプルリクエストのメタデータで関連付けます。 - 引き渡し前に、プロジェクトのレビューチェックリストを完了します。 ### 互換性 - 旧形式と新形式を併用できる場合は、破壊的変更を避けます。 - 非推奨のAPIを明確に示し、移行手順を用意します。 - 破壊的変更が避けられない場合は、リリースメタデータと変更履歴の両方で明示します。 - 移行ガイド、更新済みテスト、同期済みの生成ファイル、レビュー担当者が確認できる証拠を含めます。 - フォーマット、lint、対象を絞ったテスト、統合テスト、全テストスイート、ドキュメントチェックの実結果が揃うまで、準備完了を主張しません。