# 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.