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

자동 포매팅

풀 리퀘스트는 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 구문 검증

포맷하기 전에 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 타겟을 사용하세요. 이 타겟은 top-level C++ 파일에는 astyle을, src/ 하위 디렉터리의 C++ 파일에는 clang-format을 실행합니다.

Vim/Neovim

설정에 추가:

" 저장시 astyle로 C++ 포맷
autocmd BufWritePre *.cpp,*.h !astyle --options=.astylerc %

" deno로 포맷
autocmd BufWritePre *.md,*.ts !deno fmt %

문제 해결

"json_formatter not found" 또는 "style-json-parallel target not found"

lint 프리셋으로 CMake를 구성했거나 -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