Contributing ja

コントリビューティング

English | 中文 | 日本語 | 한국어 | Español | Português | Русский

コマンド

npm test                        # full test suite (Node built-in runner, no build needed)
node --test test/foo.test.mjs   # single file
npm run package                 # build the versioned zip (browsa-vX.Y.Z.zip)
npm run build                   # esbuild vendor bundle (only needed after build.mjs changes)
bash check-compat.sh            # static compatibility check

4GB ボックスの制約: スイートは 103 ファイル（jsdom 重視が約 36）で、2CPU/4GB の VPS 上で走る。スクリプトは同時実行を 2 に上限し、4GB では --test-concurrency=1 が望ましい。テストで数十 MB のブロブを確保してはならない（44MB のモック 1 つでボックスが OOM した実績 — 実際に再発した）。純関数テスト（DOM なし、大きなバッファなし）を優先する。

テストの哲学

• テストは、実モジュールを import する前に chrome グローバルをモックする。jsdom テストは代役ではなく、実ベンダーの marked/DOMPurify/katex/highlight.js バンドルを使う。
• sidepanel.js は export ゼロ — そのテストは sidepanel.html 全体を jsdom に読み込み、ブラックボックスで操作する（クリック／キー／ポートメッセージのシミュレート）。
• ワーカークライアントはモジュールレベルのシングルトンを持つ → 新しいシングルトンが要るシナリオは、必ず別のテスト「ファイル」にする（ランナーはファイル／プロセス毎に隔離する）。
• lockstep 規律: 複数箇所でミラーされる事実（正規表現、フィールド名、CSS／ヒントのペア、タブ順）は、1 つのソースへ畳むか、AGENTS.md の「lockstep で両方変える」注記付きのソース正規表現でピン留めする。例: subchat.test.mjs は pushSubChatChunk(… SUBCHAT_DONE …) の正確なソース行を正規表現でロックする。
• ディテールスレッド／ストリーミングのテストは、必ずターンを終わらせること（DONE / ■ / クローズ）。さもないとターンポートの 20 秒 SW_PING インターバルが漏れて、ランナーが固まる。
• WASM は「実行しない」の例外: WebAssembly.instantiate は Node で走るため、pdf-inspector テストは実ベンダーのバイナリを実行する。

リファクタリング原則（事故を通じて獲得。AGENTS.md より）

• リテラルだけが違う switch case が N 個 → 1 つのルックアップテーブル。同じワイヤプロトコルの手書き実装が 2 つ → フック付きの 1 つの共有関数（DONE ハンドラのドリフトは、現実に起きたバグファミリだった）。
• 抽出のたびに、フルスイート「と」check-compat.sh を回す — 構文チェックは何も証明しない。
• export を死んだと宣言する前に、リポジトリ全体（test/ 込み）を grep する。テスト専用の export が自動的に死んでいるわけではない — 前後のコメントを読む。

dev-preview（ヘッドレス環境での拡張 UI プレビュー）

node dev-preview/gen.mjs        # regenerate preview pages from real sidepanel.html (rerun after HTML changes)
python3 -m http.server 8931     # from the repo root
# http://127.0.0.1:8931/dev-preview/sidepanel.preview.html

chrome-shim が最小限の chrome.* サーフェスを提供し、seed.js が豊かな履歴を注入する。スクリーンショットは CDP の Page.captureScreenshot を通す（プレーン、clip/scale なし。page.screenshot() にはダークモードのアーティファクトがある）。プレビューが通ることは、実拡張が通ることと同義ではない: shim の sendMessage エンベロープは実契約をバイト単位でミラーせねばならず、CSP 系の検証は常に実拡張のロードを要する。

リリースフロー

1. manifest.json と package.json の「両方」でバージョンを上げる。
2. PR → CI グリーン → main へ squash-merge → dev をバックフィル: git reset --hard origin/main && git push --force-with-lease origin dev（マージベースのバックフィルは main..dev を汚染する。PR ページの Delete branch ボタンは dev を削除しかねない）。
3. バージョンアップの PR は、再利用可能なリリースワークフロー（xiaohuzai/release-flow@v1）を流れる（テストは免除、PAT モード）。
4. ストアリスティングの文案は .agents/skills/cws-listing スキルで生成する（タグがバージョンの真実の源）。リジェクトの履歴は記録済み。
5. ドキュメント同期の規律（ユーザーに見える変更はすべて、同一 PR で）: 両言語の README（セクション整合のミラー）→ ドキュメントサイト（両言語）→ スクリーンショット／バナー／デモ GIF／プロモ動画をそれぞれ「検討」（可読性はその素材自身の解像度で判定。変更された GIF は、キャッシュ打破のためファイル名変更が必須）→ アーキテクチャレベルの事実は AGENTS.md に記録。

レッドライン（簡易リスト）

自動コミット／パッケージング禁止（明示的な指示を待つ） · パッケージング前のフルテスト実行禁止（対象を絞ったグリーンで十分） · 現行バージョンを使い、独断でバンプしない · 拡張の秘密鍵は /root/workspace/browsa-keys/ の外に出ない · ユーザー向けの文案は専門用語を避ける（zh に英語の専門用語を持ち込まない） · 保存済みの画像ピクセルは決して破棄しない · thinking のデフォルトは omit。

---

権威版: Contributing（英語） / Contributing-zh（中文） — AI による初翻スナップショット、同期日 2026-10-01。