Rijad Zuzo
135 lines
3.6 KiB
Markdown
135 lines
3.6 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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** binary on `PATH`, or set the `GODOT_BIN` environment variable
|
|
- **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](https://github.com/bitwes/Gut/releases/tag/v9.7.1).
|
|
The downloaded release archive SHA-256 is
|
|
`14969aa46adc84aa08cdd21b9f6d1a64addd92ae60b36f02d0521ed305aa4086`.
|
|
|
|
The quality and format scripts discover `.venv` automatically; activating it
|
|
is optional.
|
|
|
|
## Usage
|
|
|
|
### Full project check
|
|
|
|
```bash
|
|
# Linux / macOS / Git Bash
|
|
./tools/quality.sh
|
|
|
|
# Windows PowerShell
|
|
& ./tools/quality.ps1
|
|
```
|
|
|
|
### Fast changed-files mode
|
|
|
|
Only runs `gdformat` / `gdlint` on `.gd` files modified since the last commit.
|
|
The Godot dependency check and all project scenarios still run.
|
|
|
|
```bash
|
|
./tools/quality.sh --changed
|
|
& ./tools/quality.ps1 -Changed
|
|
```
|
|
|
|
### Auto-format (not part of the gate)
|
|
|
|
```bash
|
|
./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-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-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 executable (auto-detected from PATH if unset) |
|
|
|
|
## CI setup
|
|
|
|
To add this to CI, install the dependencies and run:
|
|
|
|
```bash
|
|
python -m pip install -r requirements-dev.txt
|
|
./tools/quality.sh
|
|
```
|
|
|
|
The script exits non-zero on any failure, 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 when the ignored cache is absent, so a fresh clone needs no
|
|
manual editor launch. Godot/GUT script parse or load markers are failures
|
|
because headless Godot can report those errors while returning a zero process
|
|
exit code.
|