# 開発コマンド (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 を含む全テスト．シーン幾何を変えた後は一度通す
```

> ⚠ 既知の問題: `slow` 層のうち `tests/visualize/` と `tests/cli/test_visualize_cli.py` は
> VTK のインストール破損により失敗する（`import pyvista` 単体で再現）．`sm-visualize` も
> 同じ理由で実行できない．依存関係の修復が必要．

## 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` を参照．