From 6726f9c6e41deb1113da8d240a9df4f2a7663163 Mon Sep 17 00:00:00 2001
From: Fabian <fabianwgl@users.noreply.github.com>
Date: Fri, 31 Jul 2026 06:11:25 +0100
Subject: [PATCH] Add baseline quality checks (#357)

---
 .github/workflows/quality.yml |  49 ++++++++++++++
 README.md                     |  13 +++-
 scripts/check.sh              | 116 ++++++++++++++++++++++++++++++++++
 3 files changed, 176 insertions(+), 2 deletions(-)
 create mode 100644 .github/workflows/quality.yml
 create mode 100755 scripts/check.sh

diff --git a/.github/workflows/quality.yml b/.github/workflows/quality.yml
new file mode 100644
index 00000000..be9fe4e8
--- /dev/null
+++ b/.github/workflows/quality.yml
@@ -0,0 +1,49 @@
+name: Quality
+
+on:
+  pull_request:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  php:
+    name: PHP ${{ matrix.php }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        php:
+          - "8.3"
+          - "8.4"
+          - "8.5"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up PHP
+        uses: shivammathur/setup-php@v2
+        with:
+          php-version: ${{ matrix.php }}
+          coverage: none
+
+      - name: Check PHP syntax and regression tests
+        run: ./scripts/check.sh php
+
+  compose:
+    name: Docker Compose
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Validate Compose configuration
+        run: ./scripts/check.sh compose
+
+      - name: Run shell contract tests
+        run: ./scripts/check.sh shell
diff --git a/README.md b/README.md
index 935fe3a9..ead52a5a 100644
--- a/README.md
+++ b/README.md
@@ -422,8 +422,17 @@ docker compose up -d
 # Logs
 docker compose logs -f web
 
-# Validate PHP files
-find . -name '*.php' -not -path './var/*' -print0 | xargs -0 -n1 php -l
+# Run every local quality check
+./scripts/check.sh
+
+# Run only PHP syntax checks and regression tests
+./scripts/check.sh php
+
+# Run all zero-dependency regression and contract tests
+./scripts/check.sh test
+
+# Validate Docker Compose
+./scripts/check.sh compose
 ```
 
 Repository references:
diff --git a/scripts/check.sh b/scripts/check.sh
new file mode 100755
index 00000000..3f151933
--- /dev/null
+++ b/scripts/check.sh
@@ -0,0 +1,116 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+repository_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$repository_root"
+
+lint_php()
+{
+	local file
+	local linted=0
+
+	while IFS= read -r -d '' file; do
+		# This installer source is a PHP generator template. Its %TOKEN%
+		# placeholders are replaced before the generated file is executed.
+		if [[ "$file" == "install/data/constant_format.tpl" ]]; then
+			continue
+		fi
+
+		php -l "$file" > /dev/null
+		linted=$((linted + 1))
+	done < <(git ls-files -z -- '*.php' '*.tpl')
+
+	echo "PHP syntax check passed for ${linted} tracked files."
+}
+
+run_php_tests()
+{
+	local file
+	local tested=0
+
+	while IFS= read -r -d '' file; do
+		if [[ "$file" != *Test.php ]]; then
+			continue
+		fi
+
+		echo "Running ${file}"
+		php "$file"
+		tested=$((tested + 1))
+	done < <(git ls-files -z -- 'tests/*.php' 'tests/**/*.php')
+
+	if [[ "$tested" -eq 0 ]]; then
+		echo "No zero-dependency PHP tests found."
+	else
+		echo "PHP tests passed for ${tested} files."
+	fi
+}
+
+run_shell_tests()
+{
+	local file
+	local tested=0
+
+	while IFS= read -r -d '' file; do
+		if [[ "$file" != *.sh ]]; then
+			continue
+		fi
+
+		echo "Running ${file}"
+		sh -n "$file"
+		sh "$file"
+		tested=$((tested + 1))
+	done < <(git ls-files -z -- 'tests/*.sh' 'tests/**/*.sh')
+
+	if [[ "$tested" -eq 0 ]]; then
+		echo "No shell contract tests found."
+	else
+		echo "Shell contract tests passed for ${tested} files."
+	fi
+}
+
+validate_compose()
+{
+	if ! command -v docker > /dev/null 2>&1; then
+		echo "Docker is required for Compose validation." >&2
+		exit 1
+	fi
+
+	docker compose config --quiet
+	echo "Docker Compose configuration is valid."
+}
+
+usage()
+{
+	echo "Usage: $0 {all|php|lint|test|shell|compose}" >&2
+	exit 2
+}
+
+case "${1:-all}" in
+	all)
+		lint_php
+		run_php_tests
+		validate_compose
+		run_shell_tests
+		;;
+	php)
+		lint_php
+		run_php_tests
+		;;
+	lint)
+		lint_php
+		;;
+	test)
+		run_php_tests
+		run_shell_tests
+		;;
+	shell)
+		run_shell_tests
+		;;
+	compose)
+		validate_compose
+		;;
+	*)
+		usage
+		;;
+esac