開発コマンド (Development Commands)

日常の開発で使うコマンド一覧．コマンドを実行する前に必ず本ファイルを参照する（推測でコマンドを試さない）．コマンドが新しく確定・変更されたときは本ファイルを更新する．

前提: ENV_02_環境構築手順.md のセットアップが済んでいること．すべてリポジトリ直下（pyproject.toml のある場所）で実行する．OS（Windows / macOS）による差は無い．

環境 (Environment)

目的	コマンド
依存パッケージを同期（初回・`uv.lock` 更新時）	`uv sync`
依存パッケージを追加	`uv add <パッケージ>`
開発用（テスト・lint 等）の依存を追加	`uv add --dev <パッケージ>`
依存パッケージを削除	`uv remove <パッケージ>`
インストール済みパッケージを確認	`uv pip list`

※ pip install は使わない（ENV_02「環境再現性のルール」）．

起動 (Run)

目的	コマンド
アプリを起動（メイン画面）	`uv run python -m tiasjudge`
コンソールスクリプトで起動	`uv run tiasjudge`
起動可能性のみ確認（画面を出さずに終了）	`uv run python -m tiasjudge --check`
同梱学習データと診断の動作のみ確認（画面を出さない）	`uv run python -m tiasjudge --verify-data`

※ 診断を実行すると結果画面（モードレス）が開く．結果画面は表示専用で，言語切替と「閉じる」はメイン画面の「結果画面の操作」から行う． ※ ヘッドレス環境（画面の無い CI 等）では QT_QPA_PLATFORM=offscreen を付けて --check を実行する．

デバッグ用 (Debug)

結果画面の見た目を確認するためのデバッグ専用オプション．舌画像の読み込みや診断（SVM 学習）は行わず，ダミーの診断結果とダミー画像で結果画面だけを開く．

目的	コマンド
結果画面をダミー結果で開く（成功パターン）	`uv run tiasjudge --preview-result`
結果画面をダミー結果で開く（診断失敗パターン）	`uv run tiasjudge --preview-result --failed`
結果画面を英語表示で開く	`uv run tiasjudge --preview-result --english`
プレビュー画面の構築のみ確認（即終了）	`uv run tiasjudge --preview-result --check`

※ 既定は日本語表示．結果画面は表示専用（言語切替ボタンを持たない）ため，英語表示の確認には --english を使う． ※ プライマリ以外のモニタがあればそこに最大化して開く（2 画面運用の確認．SPEC_01「表示先モニタ」参照）．モニタ 1 台なら通常サイズで開く． ※ 結果画面を閉じるとアプリが終了する． ※ ダミー値は成功パターンが淡紅 55% / 紅 25% / 暗赤 10% / 紫 5% / 淡白 5%（上位 2 色は淡紅・紅），失敗パターンが旧実装の失敗時スコア組（紫 42 / 暗赤 0 / 紅 5 / 淡紅 11 / 淡白 3）． ※ オプションを付けなければ通常起動・--check の挙動は変わらない．

テスト (Test)

目的	コマンド
全テストを実行	`uv run pytest`
特定ファイルを実行	`uv run pytest tests/core/test_color.py`
特定テストを実行	`uv run pytest tests/core/test_color.py::test_xyz_to_lab`
失敗時に詳細を表示	`uv run pytest -vv`
最初の失敗で中断	`uv run pytest -x`

※ テストが 1 件も収集されない場合，pytest は終了コード 5 で終わる．テスト対象の指定ミスを疑うこと．

lint・フォーマット (Lint & Format)

目的	コマンド
lint チェック	`uv run ruff check .`
lint の自動修正	`uv run ruff check --fix .`
フォーマット実行	`uv run ruff format .`
フォーマット差分の確認のみ	`uv run ruff format --check .`

コミット前の確認 (Pre-commit Checks)

以下の 3 つがすべて通ることを確認してからコミットする．

uv run ruff check .
uv run ruff format --check .
uv run pytest

配布用ビルド (Packaging)

Windows 単体 exe（onefile・コンソール非表示）を PyInstaller で作る（PLAN_02 ステップ 8）．

目的	コマンド
exe をビルド	`uv run pyinstaller TIASjudge.spec --noconfirm`
ビルドした exe の起動確認（画面を出さない）	`dist/TIASjudge.exe --check`
ビルドした exe の同梱データ・診断確認	`dist/TIASjudge.exe --verify-data`
ビルド成果物を削除	`rm -r build dist`（PowerShell: `Remove-Item -Recurse build, dist`）

※ 成果物は dist/TIASjudge.exe（約 93 MB）．build/・dist/ は Git 管理外． ※ ビルド設定はリポジトリ直下の TIASjudge.spec，エントリスクリプトは packaging/entry.py． ※ data/data.csv は exe に同梱され，実行時に sys._MEIPASS/data/data.csv へ展開される．差し替えたい場合は環境変数 TIASJUDGE_DATA_CSV にパスを指定する． ※ ビルドは実行環境の OS 向けの成果物のみ作られる（Windows で Mac 用 app は作れない）．

同梱データ (Bundled Data)

ファイル	内容
`data/data.csv`	SVM 学習データ（旧実装の `data.csv` を UTF-8 に変換して同梱．SPEC_02 参照）

※ 変換行列 CSV・舌画像は実行時にユーザーが選択するためリポジトリに含めない．