formatting.md

title	Formatting & Linting

This guide explains how to format and lint code in Cataclysm: Bright Nights.

Quick Reference

File Type	Tool	Command
C++ (.cpp/.h)	astyle	cmake --build build --target astyle
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

Automated Formatting

Pull requests are automatically formatted by autofix.ci. If your code has style violations, a commit will be pushed to fix them.

Tip

To avoid merge conflicts after autofix commits, either:

1. Run git pull to merge the autofix commit, then continue working
2. Format locally before pushing, then git push --force if needed

C++ Formatting

C++ files are formatted with astyle.

# Install astyle (Ubuntu/Debian)
sudo apt install astyle

# Install astyle (Fedora)
sudo dnf install astyle

# Install astyle (macOS)
brew install astyle

Using CMake

# Configure (only needed once, or use an existing build)
cmake --preset lint

# Format all C++ files
cmake --build build --target astyle

The style configuration is in .astylerc at the repository root.

JSON Formatting

JSON files are formatted with json_formatter, a custom tool built from the project source.

Using CMake

# Configure (only needed once, or use an existing build)
cmake --preset lint

# Format all JSON files in parallel
cmake --build build --target style-json-parallel

# Format all JSON files sequentially (slower, but useful for debugging)
cmake --build build --target style-json

Note

The data/names/ directory is excluded from formatting because name files have special formatting requirements.

JSON Syntax Validation

Before formatting, you can validate JSON syntax:

build-scripts/lint-json.sh

This runs Python's json.tool on all JSON files to catch syntax errors.

Markdown & TypeScript Formatting

Markdown and TypeScript files are formatted with Deno.

# Install Deno
curl -fsSL https://deno.land/install.sh | sh

# Format Markdown and TypeScript
deno fmt

Lua Formatting

Lua files are formatted with dprint via Deno.

# Format Lua files
deno task dprint fmt

Dialogue Validation

NPC dialogue files have additional validation:

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

Pre-commit Workflow

Before committing, run these checks:

# Configure once (creates build directory with formatting tools)
cmake --preset lint

# Format all code
cmake --build build --target astyle           # C++
cmake --build build --target style-json-parallel  # JSON
deno fmt                                       # Markdown/TypeScript
deno task dprint fmt                           # Lua

CI Integration

The CI pipeline runs these checks automatically:

1. JSON syntax validation - build-scripts/lint-json.sh
2. JSON formatting - cmake --build build --target style-json-parallel
3. Dialogue validation - tools/dialogue_validator.py

If any check fails, the build will fail. Use the commands above to fix issues locally before pushing.

Editor Integration

VS Code

Install these extensions for automatic formatting:

• C++: C/C++ with astyle integration
• Deno: Deno for Markdown/TypeScript

Vim/Neovim

Add to your config:

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

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

Troubleshooting

"json_formatter not found" or "style-json-parallel target not found"

Make sure you configured CMake with the lint preset or with -DJSON_FORMAT=ON:

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

"astyle target not found"

Make sure astyle is installed and in your PATH:

# Check if astyle is available
which astyle

# Install if missing (Ubuntu/Debian)
sudo apt install astyle

Then reconfigure CMake:

cmake --preset lint

astyle produces different results

Make sure you're using the .astylerc from the repository root:

astyle --options=.astylerc src/*.cpp