# 開発コマンド (Development Commands)

日常の開発で使うコマンドをまとめる．人間とエージェント（tester・coder，`/auto-refactor`・`/auto-audit`）がコマンドを推測せずに済むよう，本ファイルを唯一の参照先とする．新しいコマンドが確定・変更されたら本ファイルに反映する．

## 前提 (Prerequisites)

- パッケージ管理・実行は **uv** に統一する．コマンドは原則 `uv run <...>` で実行する．
- 依存の同期: `uv sync`（`dev` グループを含めて全依存をインストール）
- Python は `>=3.12`（`pyproject.toml` の `requires-python`）．

## シミュレーション・評価 (CLI)

`pyproject.toml` の `[project.scripts]` で定義されたエントリポイント．

| コマンド | 役割 | 実装 |
| --- | --- | --- |
| `uv run sm-render <scene.yaml>` | シーン YAML をレンダリングし PNG / luminance.npy を出力 | `cli/render.py` |
| `uv run sm-evaluate <入力> <config.yaml>` | PNG / luminance.npy を評価し metrics.csv + figures/ を出力 | `cli/evaluate.py` |
| `uv run sm-visualize <scene.yaml>` | シーンを 3D 表示 / スクリーンショット出力 | `cli/visualize.py` |

各コマンドの詳細オプションは `--help` で確認する（例: `uv run sm-visualize --help`）．

## テスト (Tests)

テスト方針の詳細は `.claude/rules/testing.md` を参照．

```bash
uv run pytest                 # 通常実行
uv run pytest -m "not slow"   # 重い（レンダリングを伴う）テストを除外
uv run pytest tests/evaluation/test_roi.py   # 個別ファイル
```

- `slow` マーカーは `pyproject.toml` の `[tool.pytest.ini_options]` に登録済み．

物理モデルの健全性検査（積分球の解析解一致・法線監査・面光源の軸マッピング）は
**通常実行に含まれる**（合計 2 秒程度）．`slow` に隔離するとレンダ経路が壊れても
気づかないため（[TEST_13](../06_TEST/TEST_13_物理モデル健全性の一括監査.md)）．

```bash
uv run pytest -m ""    # slow を含む全テスト．シーン幾何を変えた後は一度通す
```

> ⚠ `vtk` は `pyproject.toml` で **9.4.2 に固定**している．9.6.1 では Windows の
> Smart App Control が 14 個の DLL をレピュテーション判定でブロックし，`sm-visualize` が
> 起動できなくなる（[TEST_13](../06_TEST/TEST_13_物理モデル健全性の一括監査.md) 検査 8）．
> バージョンを上げるときは必ず `sm-visualize` の起動確認を行うこと．
> `tests/visualize/test_vtk_import_guard.py` が通常実行で import 可否を常時検査している．

> ⚠ `mitsuba` は `pyproject.toml` で **3.7.1 に固定**している．3.8.0 では Smart App Control が
> 同梱の `IlmThread-mitsuba.dll` 1 個をブロックし mitsuba が import 不能＝レンダが全滅する
> （2026-09-01 実測．2 週間動いた後にクラウド側の判定だけが反転した．
> [TEST_16](../06_TEST/TEST_16_立方体キャビティ導入と球との比較.md) 失敗パターン参照）．
> バージョンを上げるときは import 確認と `uv run python -m pytest -m ""`（絶対放射量検証込み）を
> 必ず通し，過去レンダとの比較が続く実験中ならアンカー再レンダで等価性を確認すること．
> なお `pytest.exe` ランチャも同時にブロックされたため，テスト実行は `uv run python -m pytest` を使う．

## Lint / フォーマット (Lint & Format)

規約の詳細は `.claude/rules/coding-style.md` を参照．ruff を唯一の lint / format ツールとする．

```bash
uv run ruff check .          # 検査のみ
uv run ruff check . --fix    # 自動修正
uv run ruff format .         # フォーマット適用
```

## 環境変数 (Environment Variables)

- `DRJIT_LIBLLVM_PATH` — Mitsuba の LLVM JIT に必要（未設定時は `runtime/llvm_init.py` が標準パスを自動探索）．詳細は `docs/02_ENV/ENV_02_環境構築手順.md` を参照．