開発への参加
開発への参加
Section titled “開発への参加”Node 24 以降と Bun 1.4.0 をインストールし、bun install --frozen-lockfile --ignore-scripts を実行してください。1つのパッケージだけなら bun run turbo run build typecheck --filter=@alneas/appkit-core（または appkit-react）を使用します。実装が変わっていない場合、無関係な統合テストを再実行しないでください。
- 所有元のソースと API の JSDoc を変更します。
- 正確な公開インポートのサブパスを含め、対応する英語の機能ガイドを更新します。インストールコマンドにはサブパスではなくパッケージ名を使用します。
- 影響を受けるテストと、パッケージング・型の検査を実行します。PR にコマンドを記録し、再利用した検証結果を明示します。
- 問題と変更後の動作を説明する PR を作成します。バージョン 0.1.0 は公開済みです。以後のバージョン変更は内部の固定バージョン指定と併せて確認してください。作業ツリーの変更は将来のリリース候補であり、既存の npm バージョンを更新するものではありません。
bun run check:release は公開エントリーの読み込み、ルート API、パッケージに含まれるファイルを検査します。bun run check:docs は選択したソース、サブパス、相対リンクを検査します。ビルドでエクスポートリファレンスと AI 索引を生成するため、生成ファイルを手作業で編集しないでください。
通常のCIでは、ビルド、型チェック、ユニットテストにTurboのキャッシュを使用します。ブラウザー／データベースのチェックは、それぞれの統合境界に変更があった場合に選択されます。リリースでは、ソースと完全に同じコミットで成功したmainの品質検証実行を、ブラウザー検証の証跡として再利用します。キャッシュヒットは、ソース、ヘルパー、依存関係、Node/Bun/プラットフォームのランタイムが一致する、過去の成功結果です。
一時的なフィクスチャは .verification/tmp、ログは .verification/logs に保存してください。パッケージ化した配布物の利用側検証には、システムの一時領域に作る使い捨てディレクトリを使用し、未宣言のインポートがチェックアウトの node_modules を通じて解決されることを防ぎます。どちらも Git と公開 manifest の対象外です。公開と非公開は独立したリポジトリとロックファイルを維持し、非公開側は公開済みの正確なバージョンを使用します。明示的に選択した使い捨ての利用側フィクスチャだけが、レジストリのバージョンをレビュー済み tarball に置き換えます。
ignore 対象のファイルも、そのまま安全に共有できるわけではありません。archives.json を含む検証記録には、アーカイブの絶対パスや環境の詳細が含まれる場合があります。ハッシュを引き続き使えるよう原本はローカルに保持し、共有前に別のコピーを確認して必要箇所を伏せてください。.verification/ の生のファイルを CI の成果物としてアップロードしたり、Git に強制追加したりしないでください。一致した値を表示せずにログ内の認証情報を検査し、漏えいが確認された認証情報は失効させてください。
コミット前に git var GIT_AUTHOR_IDENT と git var GIT_COMMITTER_IDENT を確認してください。今後の公開コミットに個人メールを残したくない場合は、リポジトリ固有の Git 設定に GitHub 提供の noreply アドレスを使用します。設定変更で過去の履歴からアドレスは消えません。履歴を書き換える場合は別途調整してください。
翻訳、取り込み、デプロイはポータルが担います。https://tech-docs.alneas.com/policies/documentation-policy.md と https://tech-docs.alneas.com/skills/document-authoring/SKILL.md に従ってください。GitHub のルート README は通常の Markdown とし、ポータルの概要ページには独自の frontmatter を付けます。
ローカルの品質検査
Section titled “ローカルの品質検査”bun install --frozen-lockfile --ignore-scripts の後、各 clone で bun run secrets:setup と bun run hooks:install を一度実行してください。インストーラーは固定バージョンの Gitleaks をダウンロードし、SHA-256 を検証します。macOS と Linux の arm64・x64 に対応します。ほかのプラットフォームでは、同じバージョンの Gitleaks を PATH または APPKIT_GITLEAKS_BINARY で指定できます。プロバイダーの認証情報は不要です。
Husky は各コミットの前に bun run secrets:staged と bun run lint:staged を実行します。スキャナーがない場合や検査に失敗した場合はコミットを止めます。Gitleaks は出力をマスクしてステージ済みの Git 差分を検査し、lint-staged はステージ済みの JavaScript・TypeScript・JSON ファイルに読み取り専用の Biome lint 検査を実行します。どちらも自動整形は行わず、未ステージの変更には触れません。一部だけをステージしたファイルでは作業コピーを lint 検査するため、コミット前に未完成の編集を分離してください。
プッシュ前に、Huskyがbun run verify:pushを実行します。このコマンドは常に履歴内の
シークレットをスキャンし、ソースのlintを実行します。その後、変更された入力に基づいて、パッケージ、ドキュメント、ツール、
React/Core互換性、ブラウザーのチェックを選択します。Turboは、
一致するビルド／型チェック／ユニットテストの結果を再利用します。このコマンドは、実モデルの評価や
パッケージの公開は行いません。Gitフックは回避できるため、Node 24のCIジョブも、Gitleaksのインストール後に同じ
セレクターとランナーを使用します。Node 26では、影響を受けるパッケージの
ビルド、型チェック、ユニットテストを実行します。CIの実行タイミングは引き続き、mainの更新時または手動ディスパッチ時のみです。
影響に応じた検証の選択
Section titled “影響に応じた検証の選択”ローカルでの選択では、HEADとorigin/mainのマージベースを、ステージ済み、未ステージ、未追跡のファイルを含む
作業コピーと比較します。作業を始める前にmainをフェッチしてください。
CIでは、実行対象の正確なコミットを、その祖先にあたる、直近で成功したmain-pushのPublic
quality実行と比較します。失敗、キャンセル、後続の実行に置き換えられた実行では、
この基準点は更新されません。次の実行には、未検証の変更がすべて含まれます。履歴またはAPIの証跡から
基準点を確定できない場合は、検証ゲート全体を実行します。手動ディスパッチでも
検証ゲート全体を実行しますが、リリースに必要なmain-pushの証跡の代わりにはなりません。
| 変更された入力 | 選択されるチェック |
|---|---|
| 解析後のコードが変わらない説明文またはソースコメント／JSDoc | ドキュメントのチェックと、その前提となるビルド。ブラウザーテストとパッケージのユニットテストは実行しません |
| ストーリーまたはそのローカルヘルパー | それらをインポートするストーリー、およびStorybookの契約／型チェック |
| Reactの実装 | パッケージの契約チェック、ビルド／型チェック／ユニットテスト、ドキュメント、Core互換性、および推移的にインポートするストーリー |
| Coreの実装 | パッケージの契約チェック、ビルド／型チェック／ユニットテスト、ドキュメント、Core互換性、および推移的にインポートするストーリー。変更されたCoreモジュールをインポートするストーリー／プレビューがない場合、ブラウザーテストは実行しません |
| パッケージのユニットテストのみ | パッケージのビルド／型チェック／ユニットテスト |
| 公開／デプロイのヘルパー、またはそれらのワークフロー | 対応するツールのテスト。ブラウザーテストスイートは実行しません |
| 既知の検証オーケストレーション | 検証ツールのテスト。ブラウザーテストスイートは実行しません |
| 品質検証ワークフロー／ランタイムの設定 | Node/Bun/ランナー／インストールの変更が実行に影響する可能性があるため、検証ゲート全体 |
| パッケージのバージョンのみの変更、または解決済みの依存関係が同一であるロックファイル内のワークスペースバージョンの変更 | リリース／ドキュメントのチェックと、その前提となるビルド。ブラウザーおよびユニットテストのスイートは実行しません |
| 実際の依存関係／ロックファイルの解決結果の変更 | 検証ゲート全体。リリースメタデータとしては扱いません |
| グローバルCSS／アセット、依存関係、共有設定、削除されたUIモジュール、または不明な入力 | 検証ゲート全体 |
ストーリーの選択では、相対インポート／再エクスポート、文字列リテラルによる動的インポート、
ReactとCoreの公開サブパスエクスポートをたどります。TypeScriptソースに解決される
NodeNextの.js指定子も対象です。明示的なimport type/export type宣言は
ランタイムでは消去され、パッケージの型チェックで検証されます。プレビューのデコレーター／ローダー／セットアップは、
すべてのストーリーで共有されます。生成されたParaglideモジュールは、内部を解析しない依存関係として扱います。その
ロケール／設定の入力が変更されると、検証ゲート全体が選択されます。JSX/TypeScript/Viteのコンパイラーディレクティブは、
コメント内に記述されていてもコードの入力として扱います。
未解決のインポート、計算された指定子による動的インポート、globインポート、未対応のマッピングがある場合は、
すべてのストーリーを対象にします。循環インポートも安全にたどります。選択された各ストーリーは、
引き続き4つすべてのブラウザー条件で、同じメモリーガードと、違反時に実行を失敗させるアクセシビリティチェックを使用して実行されます。
セレクターはテスト名からの推測を使用せず、不明なファイルを黙って対象から外すこともありません。
各CIジョブは基準点と選択結果の概要を示します。ローカルの実行計画は、無視対象の.verification/quality-plan.jsonに記録されます。
選択されたStorybookスイートは、Reactのtest:browser Turboタスクとして実行されます。そのキーには、
正規化してソートしたストーリーの選択結果、React/Coreのソースとビルド済みエントリー、
Storybook/Vitestの設定、翻訳／アセット、メモリーガードのヘルパー、
ロックファイル、Node/Bun/プラットフォーム／アーキテクチャ、CIイメージ、関連する環境が含まれます。一部の
スイートの結果を、別の選択結果やスイート全体の結果として使用することはできません。キャッシュされるのは、成功したタスクの
実行結果だけです。キャッシュヒット時には過去のブラウザー出力を抑制し、再生されたログが
新たなブラウザー実行に見えないようにします。キャッシュミス時には、従来どおりの4つのブラウザー条件を、
1ワーカー、3ファイル単位のバッチで実行します。Coreのみの変更でも、関連するユニットテスト／型チェックと
2種類のCoreによるマトリックスを実行します。UIテストの要否はインポート解析で判断します。
不明な入力、読み取れないメタデータ、解決済みの依存関係の変更については、引き続き
保守的に判断します。バージョンのみの変更かどうかは、コミットメッセージやファイル名ではなく、
ファイルの内容を比較して検出します。成功した祖先コミットのソース品質検証結果を利用できるのは、
蓄積された変更のすべてがセレクターで網羅されている場合に限られます。
通常のチェックをすべて実行するにはbun run verify:fullを使用し、
ローカルでの選択結果とコマンドを確認するにはbun run verify:push --dry-runを使用してください。
bun run test:consumerは、引き続き明示的に実行するパッケージアーカイブの利用側チェックであり、
公開時には必須のチェックです。Public qualityの成功は、選択された変更が検証されたことを示します。
説明文が変わるたびに、すべてのストーリーが再実行されたことを意味するものではありません。
パッケージごとの安定版GitHub Releaseには、独立したpublish.ymlワークフローを使用します。
appkit-core-vX.Y.Zまたはappkit-react-vX.Y.ZのReleaseを公開すると検証が始まり、
そのパッケージのみが、npmメンテナーによる2FA付き承認を待つステージに配置されます。手動の
完了ディスパッチで、承認済みのバイト列／タグを確認し、Deploymentを記録します。Releaseを公開する前に、リリース手順を参照してください。
タグのプッシュだけではnpmパッケージは公開されません。
完全な検査には bun run check:react-core も含まれます。正確に指定されたレジストリ上の Core 依存と、新しい Core アーカイブの両方について、別々の一時インストールで React の型、単体テスト、パッケージ化した配布物の利用側での SSR・読み込みを検査します。ネットワークアクセスが必要です。React の利用者に届ける必要がある Core の修正には、ID、必要となる最初の Core バージョン、理由、取り込みを予定する React バージョンを react-core-policy.json に追加してください。その取り込みバージョンまでは、Core の準備時に React の公開済み依存を維持できます。検査では要件を保留中として報告します。期限に達しても依存が古い場合は CI を止め、bun run check:react-core --release は互換性テストが通っていても、必要な修正がすべて取り込まれるまで React の公開をすべて止めます。リリース手順を参照してください。
Biome は到達不能コード、安全でない finally ブロック、debugger 文、重複する引数名の4規則から始め、違反をブロックします。より広いスタイル規則は、別途レビューした変更で追加できます。選択したファイルを明示的に整形する場合は bun run format -- path/to/file.ts を使用してください。生成物、ビルド成果物、ローカルの検証ファイルは Biome のソース対象外です。認証情報にダミーと記載されているだけで、アプリケーションのテストや例を秘密情報スキャンから除外しないでください。
Biome の互換性診断を抑制する限定的なソースコメントが2か所あります。AI SDK トランスポート内の TypeScript の resolution-mode 型インポートと、ラベル付きリソース検索ループの後にある到達可能なブロックです。これらは出力される実行時の動作を変えず、ファイル全体を lint 対象外にもしません。CSS パーサーでは Tailwind ディレクティブを有効にしています。Biome の更新時には、これらの例外を見直してください。
Storybook の開発
Section titled “Storybook の開発”リポジトリのルートで bun run storybook を実行し、http://localhost:6006 を開いてください。このコマンドは公開 Core をビルドし、React の翻訳を生成してから、分離した Vite ワークスペースを起動します。bun run check:storybook はストーリーの型と公開インポートの境界を検査し、bun run build-storybook は packages/appkit-react/storybook-static/ に静的プレビューを生成します。
ストーリーとそのメモリ内プロバイダーは packages/appkit-react/stories/ に配置し、ライブラリのビルドと npm の配布内容から除外します。個別ストーリーと組み合わせ例の両方を、この公開リポジトリが所有するコンポーネントと依存関係に限定してください。企業固有の画面は、所有元の非公開リポジトリに置きます。
プレビューは Appkit CSS、テーマ状態、選択したストーリーごとの独立した QueryClient を提供します。認証とフォームのストーリーには、それぞれ模擬認証とメモリ内データプロバイダーを追加します。これらのフィクスチャは分離した UI 状態を示すもので、ホストされた認証、永続化、バックエンドのアクセス制御を検証するものではありません。コンポーネントの説明には、正確な公開インポート先と必要な設定を記載します。技術説明は英語で維持し、ローカライズ済みの UI フィクスチャを保持してください。
このガイドを変更したら、bun run docs:generate と bun run check:docs を実行し、生成されるポータル向けコピーを更新・検証してください。文書の生成には両パッケージのビルドが必要です。クリーンなチェックアウトでは先に bun run build を実行してください。
ブラウザー検証
Section titled “ブラウザー検証”bunx --no-install playwright install chromiumで、固定されたバージョンのChromiumを一度インストールしてください。
LinuxのCIでは--with-depsを追加します。スイート全体を実行するにはbun run test:storybookを実行してください。
影響を受けるサブセットは、verify:pushとNode 24の品質検証ジョブによって選択されます。
全体を網羅するには、bun run verify:fullまたは品質検証の手動ディスパッチを使用してください。
公開には、対象コミットで成功したmain-pushのPublic quality実行が必要であり、
公開時にこのブラウザースイートを再実行することはありません。
すべての CSF3 ストーリーは Chromium の 1280×900 と 390×844 で、ライト・ダーク両モードを対象に、axe の違反を失敗として検査します。プレビューとブラウザーランナーは、実際の Appkit CSS を Tailwind でコンパイルします。パレットのストーリーは両モードの default、blue、green、rose、orange、future を対象に、適用されたクラスを検証し、アルファ合成を含む意味別テキストトークンのコントラストを確認します。モーダル・セレクト・ポップオーバーを開くストーリーでは、実際のポータルを検査します。ホスト独自の任意の色は、ホスト側での検証が必要です。
HTTP ライフサイクルのストーリーでは、未処理のリクエストを拒否するブラウザー MSW、Fetch ベースのホストアダプター、共通の Zod 応答スキーマ、実際の公開認証・プロフィール・データ・ファイルコンポーネントを使用します。認証・プロフィール、テーブル、フォーム、ファイルブラウザーの組み合わせは、読み込み中、成功、空、エラー、サインアウト済み、制限あり、特権ありの状態を対象にします。ネイティブのファイルプレビューでは、読み込み中、テキスト、0バイトのデータ、ネットワーク拒否、2xx 以外の HTTP 応答を検証します。操作ストーリーは実際のクリック、キーボード操作、フォーカスの復帰を使用し、レイアウト検査は領域内への収まり、はみ出し、タップ対象、文字の切れ、重なりを測定します。これらは分離したコンポーネントとホストの契約のテストであり、ホストされた ID 基盤、データベースの認可、初期データを投入したバックエンドでの E2E の検証結果ではありません。
ランナーは1 worker で3つのストーリーファイルを同時に実行し、4つのモード・画面サイズの組み合わせを順番に処理します。各バッチは新しい Vite・Chromium のプロセスツリーを使用します。RSS の合計は 3 GiB と物理メモリの3分の1の小さい方、Node のヒープは 1.5 GiB、1バッチは10分を上限とします。リソースの上限超過やプロセス調査の失敗は実行の失敗とし、ストーリーは省略しません。ガードは完了、失敗、中断の際、切り離されたブラウザーの子孫プロセスも含め、自身の起動に属するプロセスグループだけを終了します。並行するエージェントで別のブラウザースイートを起動しないでください。上限に達したらバッチサイズや並列数を減らし、通すために上限を引き上げたり検証を弱めたりしないでください。ランナーは測定したピーク値を表示します。node --test scripts/guarded-process.test.mjs はガードの失敗と後片付けを検査します。ガードとその回帰テストは github-docs から取り込んだテンプレートです。scripts/lib/README.md に正本のリポジトリ、固定リビジョン、ファイルの対応、更新手順を記録しています。共通の動作は github-docs で管理し、Appkit 固有の予算とバッチ処理はこのリポジトリのランナーで管理してください。
axe は支援技術やデザインのレビューを代替できません。このスイートはスクリーンショットの基準画像を生成しません。意図した見た目の変更にも、人による承認が必要です。