Local Quality Gate

A single command to detect broken GDScript, formatting issues, lint problems, parser errors, and LLM-generated garbage before committing.

Requirements

Python 3 with the pinned gdtoolkit (gdscript-toolkit). The recommended setup uses uv and a project-local environment:
```
uv venv .venv
uv pip install --python .venv/bin/python -r requirements-dev.txt
```
On Windows, use .venv/Scripts/python.exe for the --python value.
Godot 4.7.x binary on PATH, or set the GODOT_BIN environment variable. The gate rejects other engine series before importing or testing.
GUT 9.7.1 is vendored under addons/gut for Godot 4.7. No separate package-manager install is needed.

The vendored addon comes from the official bitwes/Gut v9.7.1 release. The downloaded release archive SHA-256 is 14969aa46adc84aa08cdd21b9f6d1a64addd92ae60b36f02d0521ed305aa4086.

The quality and format scripts discover .venv automatically; activating it is optional. Missing gdformat or gdlint is a gate failure rather than a silent skip.

Usage

Full project check

# Linux / macOS / Git Bash
./tools/quality.sh

# Windows PowerShell
& ./tools/quality.ps1

Fast changed-files mode

Only runs gdformat / gdlint on tracked changes and new untracked .gd files. The Godot dependency check and all project scenarios still run.

./tools/quality.sh --changed
& ./tools/quality.ps1 -Changed

Auto-format (not part of the gate)

./tools/fix_format.sh

What it checks

Check	Tool	What it detects
godot-import	Godot 4.7 headless importer	Missing or stale global `class_name` cache on fresh clones
gdformat	Game-owned GDScript roots	Formatting without rewriting addons or demos
gdlint	Game-owned GDScript roots	Lint violations such as unused arguments and naming
godot-check	Headless definitions scenario	Parser errors and missing dependencies
scenarios	Every `tests/*_test.gd` script	Simulation, persistence, navigation, and presentation regressions
gut	Vendored GUT 9.7.1 CLI	Focused unit regressions under `tests/unit/`

Output

If everything passes:

QUALITY RESULT: PASS
Godot: 4.7.stable.official.5b4e0cb0f

  godot-import PASS
  gdformat     PASS
  gdlint       PASS
  godot-check  PASS
  scenarios    PASS
  gut          PASS

Full logs:
  logs/quality/latest/

On failure, only relevant errors and fix suggestions are shown:

QUALITY RESULT: FAIL
Godot: 4.7.stable.official.5b4e0cb0f

  godot-import PASS
  gdformat     FAIL
  gdlint       FAIL
  godot-check  PASS
  scenarios    PASS
  gut          PASS

    res://simulation/SimNPC.gd:42 Unused argument 'delta'
    res://simulation/task_manager.gd:88 Line too long (120 > 100)

  NEXT FIX:
    1. Fix unused-argument in SimNPC.gd
    2. Run gdformat to auto-format files

Full logs:
  logs/quality/latest/

Full logs are always written to logs/quality/latest/ and never dumped to the terminal.

Environment variables

Variable	Description
`GODOT_BIN`	Path to the Godot 4.7.x executable (auto-detected if unset)

CI setup

To add this to CI, provide a Godot 4.7.x executable, install the dependencies, and run:

python -m pip install -r requirements-dev.txt
./tools/quality.sh

The script exits non-zero on any failure, including a wrong Godot series or missing pinned formatter/linter, so it will fail the CI step.

The shell gate isolates Godot's cross-platform user-data paths under logs/quality/godot_profile. Before running scenarios it imports project and GUT global classes whenever GDScript changes, so fresh, renamed, and deleted class_name scripts cannot leave the ignored cache stale. Godot/GUT script parse or load markers are failures because headless Godot can report those errors while returning a zero process exit code. Every Godot subprocess has a portable watchdog on stock macOS as well as Linux/Windows, and nonzero gdformat/gdlint exits fail the gate even when their output is not a familiar diagnostic string. Import receives a 60-second timeout on both shell and PowerShell; the focused checks retain their 30-second timeout.

4.2 KiB Raw Blame History