このガイドでは、Cataclysm: Bright Nightsにおけるコードの整形と静的解析の方法について説明します。

クイックリファレンス

ファイル形式	ツール	コマンド
C++ (.cpp/.h)	astyle/clang-format	cmake --build build --target format
JSON	json_formatter	cmake --build build --target style-json-parallel
Markdown	deno fmt	deno fmt
TypeScript	deno fmt	deno fmt
Lua	dprint	deno task dprint fmt

自動フォーマット

プルリクエスト(PR)は、autofix.ciによって自動的にフォーマットされます。コードにスタイル違反がある場合、修正のためのコミットが自動的にプッシュされます。

C++ のフォーマット

トップレベルの C++ ファイルは astyleを使用してフォーマットします。ソースのサブディレクトリにある C++ ファイルは clang-formatを使用してフォーマットします。

# フォーマッタのインストール (Ubuntu/Debian)
sudo apt install astyle clang-format

# フォーマッタのインストール (Fedora)
sudo dnf install astyle clang-tools-extra

# フォーマッタのインストール (macOS)
brew install astyle clang-format

CMake を使用する場合

# 設定(一度だけ実行、または既存のビルドを使用)
cmake --preset lint

# すべてのC++ファイルをフォーマット
cmake --build build --target format

スタイルの設定は、リポジトリのルートにある .astylerc と .clang-format に記述されています。

JSON のフォーマット

JSONファイルは、プロジェクトのソースからビルドされたカスタムツール json_formatterを使用してフォーマットします。

CMake を使用する場合

# 設定(一度だけ実行、または既存のビルドを使用)
cmake --preset lint

# すべてのJSONファイルを並列でフォーマット
cmake --build build --target style-json-parallel

# すべてのJSONファイルを順次フォーマット (低速ですがデバッグに便利です)
cmake --build build --target style-json

JSONの構文チェック (Validation)

フォーマットを行う前に、JSON の構文を検証できます:

build-scripts/lint-json.sh

これはすべてのJSONファイルに対してPythonの json.tool を実行し、構文エラーを検出します。

Markdown & TypeScript のフォーマット

MarkdownおよびTypeScriptファイルはDenoを使用してフォーマットします。

# Deno のインストール
curl -fsSL https://deno.land/install.sh | sh

# Markdown と TypeScript のフォーマット
deno fmt

Lua のフォーマット

Luaファイルは、Deno 経由でdprintを使用してフォーマットします。

# Lua ファイルのフォーマット
deno task dprint fmt

ダイアログのバリデーション

NPCのダイアログファイルには、追加の検証項目があります:

tools/dialogue_validator.py data/json/npcs/* data/json/npcs/*/* data/json/npcs/*/*/*

コミット前のワークフロー

コミットする前に、以下のチェックを実行してください:

# 設定の実行 (フォーマットツールを含むビルドディレクトリを作成)
cmake --preset lint

# すべてのコードをフォーマット
cmake --build build --target format           # C++
cmake --build build --target style-json-parallel  # JSON
deno fmt                                       # Markdown/TypeScript
deno task dprint fmt                           # Lua

CI 連携

CI パイプラインでは、以下のチェックが自動的に実行されます:

1. JSON 構文の検証 - build-scripts/lint-json.sh
2. JSON フォーマット - cmake --build build --target style-json-parallel
3. ダイアログのバリデーション - tools/dialogue_validator.py

いずれかのチェックに失敗すると、ビルドは失敗します。プッシュする前に、上記のコマンドを使用してローカルで問題を修正してください。

エディタの統合

VS Code

自動フォーマットのために以下の拡張機能をインストールしてください:

• C++: C/C++ astyle 連携を 有効にする
• Deno: Deno Markdown/TypeScript用

Visual Studio

PowerShell でフォーマッタを一度インストールします。LLVM には clang-format と clang-tidy が含まれます。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
scoop install llvm astyle
clang-format --version
clang-tidy --version
astyle --version

Scoop をすでにインストールしている場合は、scoop install llvm astyle だけを実行してください。バージョン確認コマンドが 見つからない場合は、PowerShell と Visual Studio を閉じて開き直し、PATH を再読み込みしてください。

ツールをインストールした後:

1. リポジトリのフォルダを Visual Studio で CMake プロジェクトとして開きます。
2. CMake を構成します。フォーマッタをインストールする前に Visual Studio がプロジェクトを構成していた場合は、 CMake キャッシュを再構成します。
3. View > Other Windows > CMake Targets View を開きます。
4. コミット前に format ターゲットをビルドします。

Visual Studio の通常の Format Document コマンドは、このターゲットを実行しません。 リポジトリのスタイルを適用するには format ターゲットを使用してください。このターゲットはトップレベルの C++ ファイルには astyle を、src/ サブディレクトリ内の C++ ファイルには clang-format を実行します。

Vim/Neovim

設定ファイルに以下を追加してください:

" Format C++ with astyle on save
autocmd BufWritePre *.cpp,*.h !astyle --options=.astylerc %

" Format with deno
autocmd BufWritePre *.md,*.ts !deno fmt %

トラブルシューティング

"json_formatter not found" または "style-json-parallel target not found"

CMakeの設定を lint プリセット、または -DJSON_FORMAT=ONを指定して行っているか確認してください:

cmake --preset lint
cmake --build build --target json_formatter

"format target not found"

astyle と clang-format がインストールされており、PATH が通っているか確認してください:

# フォーマッタが利用可能か確認
which astyle
which clang-format

# インストールされていない場合 (Ubuntu/Debian)
sudo apt install astyle clang-format

その後、CMake を再構成します:

cmake --preset lint

C++ フォーマッタの実行結果が異なる

リポジトリのルートにあるフォーマッタ設定を使用しているか確認してください:

astyle --options=.astylerc src/*.cpp
clang-format -i src/utils/*.cpp src/utils/*.h