포매팅 및 린팅

Cataclysm: Bright Nights에서 코드를 포맷하고 린트하는 방법을 설명합니다.

빠른 참조

범위	도구	명령어
staged 파일	모든 포매터	`just fmt`
모든 파일	모든 포매터	`just fmt --all`
C++ (`.cpp/.h`)	astyle/clang-format	`just fmt-cpp`
JSON	json_formatter	`just fmt-json`
Markdown/TS	deno fmt	`just fmt-docs`
Lua	dprint	`just fmt-lua`

자동 포매팅

풀 리퀘스트는 autofix.ci에 의해 자동으로 포맷됩니다. 코드에 스타일 위반이 있으면 수정 커밋이 푸시됩니다.

Tip

autofix 커밋 후 머지 충돌을 피하려면:

git pull을 실행하여 autofix 커밋을 머지한 후 작업을 계속하거나
푸시하기 전에 로컬에서 포맷한 다음 필요시 git push --force

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

스크립트 사용

just fmt-cpp
# 또는
build-scripts/format-cpp.sh

스타일 설정은 저장소 루트의 .astylerc와 .clang-format에 있습니다.

JSON 포매팅

JSON 파일은 프로젝트 소스에서 빌드된 커스텀 도구 json_formatter로 포맷됩니다.

스크립트 사용

just fmt-json
# 또는
build-scripts/format-json.sh

이 스크립트는 out/build/json-format에 json_formatter를 빌드하고 JSON 파일을 포맷합니다. 구성된 게임 빌드나 CMake 프리셋은 필요하지 않습니다. 필요하면 CATA_JSON_FORMAT_BUILD_DIR로 보조 빌드 디렉터리를 바꿀 수 있습니다.

Note

data/names/ 디렉토리는 이름 파일이 특별한 포맷 요구사항을 가지고 있어 포맷에서 제외됩니다.

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/*/*/*

커밋 전 워크플로우

prek를 사용하는 선택적 pre-commit 훅을 설치할 수 있습니다:

prek install
# 또는
just hooks-setup

커밋할 때 훅은 just fmt를 실행합니다. Deno와 dprint는 일반적으로 실행되고, C++ 및 JSON 포매터는 staged된 생성/수정 파일만 처리합니다. 포맷된 staged 파일은 같은 커밋에 포함되도록 다시 git add됩니다.

staged 파일에 같은 포매팅을 수동으로 실행하려면:

just fmt

훅 없이 커밋하기 전에 실행할 명령:

# staged 파일 포맷
just fmt

# 포맷 가능한 모든 파일 포맷
just fmt --all

CI 통합

CI 파이프라인은 이러한 검사를 자동으로 실행합니다:

JSON 구문 검증 - build-scripts/lint-json.sh
JSON 포매팅 - build-scripts/format-json.sh
대화 검증 - 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를 다시 읽게 하세요.

도구를 설치한 뒤:

저장소 폴더를 Visual Studio에서 CMake 프로젝트로 엽니다.
CMake를 구성합니다. 포매터를 설치하기 전에 Visual Studio가 프로젝트를 이미 구성했다면 CMake 캐시를 재구성합니다.
View > Other Windows > CMake Targets View를 엽니다.
커밋하기 전에 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"

JSON 포매터 스크립트를 실행하세요. 보조 포매터를 자동으로 구성하고 빌드합니다:

build-scripts/format-json.sh

C++ 포매터를 찾을 수 없음

astyle과 clang-format이 설치되어 있고 PATH에 있는지 확인하세요:

# 포매터가 사용 가능한지 확인
which astyle
which clang-format

# 없으면 설치 (Ubuntu/Debian)
sudo apt install astyle clang-format

그런 다음 다시 실행하세요:

build-scripts/format-cpp.sh

C++ 포매터가 다른 결과를 생성

저장소 루트의 포매터 설정을 사용하는지 확인하세요:

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