pc to lokalne bramki jakości dla projektów PHP, zbierane w jednym poleceniu vendor/bin/pc:
analiza statyczna (PHPStan), zapachy kodu (PHPMD), formatowanie (Pint albo PHPCS), testy, mutacje
i kontrole procesu. Ma działać tak samo w wielu repo: wspólny kod bramek w paczce, a wybór bramek,
ścieżek i wyjątków w małym pliku pc.json repo-konsumenta.
Status: szkielet (0.1.0), silnik w budowie. Paczka ma wejście
bin/pc, kontrakt konfiguracji, silnikpc runi CI. Bramki są przenoszone z repo, w którym powstały, według planu przeniesienia. Do czasu wydania 1.0.0 interfejs może się zmieniać.
composer require --dev citycouriers/pc
vendor/bin/pc --version
vendor/bin/pc config:validate pc.json
vendor/bin/pc run # włączone bramki; kody wyjścia 0, 1, 2, 3, 4, 5, 130
vendor/bin/pc run --staged # pliki ze stage'a
vendor/bin/pc run --format=json # jeden dokument JSON (schemat: docs/schema/pc-run-1.json)Silnik odróżnia „przeszła” od „nie przeskanowano”: brak narzędzia, awaria bramki albo bramka bez kodu to kod 4, nigdy zielone
(kontrakt wyniku). Do czasu przeniesienia bramek włączone bramki są jeszcze
gate_not_implemented.
Paczka wymaga PHP ^8.4. Projekt z niższym require.php (np. wtyczka WordPress) instaluje pc
w osobnym katalogu narzędzi, żeby nie podnosić wymagań własnej paczki: zob.
docs/konfiguracja.md.
Przykład pc.json:
{
"version": 1,
"standard": "phpcs",
"paths": { "src": ["src"], "tests": ["tests"] },
"gates": { "format": true, "phpstan": true, "phpmd": true, "mutation": false },
"rulesets": { "phpmd": "vendor/citycouriers/pc/rulesets/phpmd.xml" },
"modules": { "wordpress": true, "laravel": false }
}- Rdzeń nie zależy od frameworka. Moduły (
laravel,wordpress) włącza konfiguracja konsumenta. - Jeden surowy zestaw PHPMD dla całego kodu. Odstępstwa zapisuje konsument w swoim repo, z uzasadnieniem.
- Bramka bez kontroli ujemnej nie liczy się jako bramka. Zielone CI samo nie dowodzi, że bramka cokolwiek wykrywa, więc każda bramka ma test, który musi ją zatrzymać (docs/bramki.md).
- Wersjonowanie SemVer z regułą dla bramek: major = nowa bramka blokująca albo ostrzejsze reguły, minor = nowa bramka raportująca, patch = poprawka (docs/wydania.md).
| Dokument | Zawartość |
|---|---|
| docs/index.md | Spis dokumentacji |
| docs/bramki.md | Kontrakt bramek i kontroli ujemnych |
| docs/konfiguracja.md | pc.json, moduły, instalacja |
| docs/proces.md | Zgłoszenia, etykiety P/T, audyt, PR i kontrole CI |
| docs/wydania.md | SemVer dla bramek, proces wydania |
| docs/plan-przeniesienia.md | Co i kiedy trafia do paczki |
composer install
composer hooks # włącza hook pre-commit
composer check # Pint, PHPStan, PHPMD, testy, kontrole ujemne (zawsze pełny zestaw; hook skraca zakres do typów plików)
npm test # testy skryptów procesu (bramka audytu, etykiety, quality-gate)
composer privacy # skan ścieżek maszyn i adresów e-mail
composer mutate # mutacje Pest Mutate na src: kontrole, manifest i werdykt (wymaga pcov albo xdebug)Mutacje uruchamiamy tylko przez composer mutate (scripts/mutation/mutate.php, opcje: composer mutate -- --help).
Skrypt sam składa polecenie Pesta, przed biegiem sprawdza na zestawie kontrolnym, że mutant bez asercji przeżywa, a mutant
z asercją ginie (kontrola zerowa i dodatnia), uruchamia pełny zestaw testów pod wrapperem plików wtyczki bez mutacji
(kontrola tożsamościowa), a po biegu zapisuje manifest build/mutation/manifest.json z logiem i dziennikiem. Kod 0
oznacza bieg kompletny bez żywych mutantów poza rejestrem; każdy inny wynik to kod 1 z powodami. Wtyczka Pest Mutate
5.0.2 na Windows liczy część mutantów jako zabite, choć proces mutanta nie uruchomił testu, dlatego repo ładuje lokalną
kopię jej klasy MutationTest (scripts/mutation/patch/, licencja MIT, strażnik dryfu w testach).
Bramki plików GitHub (hook uruchamia je tylko przy zmianie .github/**, .sh, .githooks/**) wymagają narzędzi lokalnie
(w CI są instalowane w przypiętych wersjach). Brak narzędzia to głośny błąd z instrukcją. Windows:
winget install --id rhysd.actionlint --exact --version 1.7.12
winget install --id zizmor.zizmor --exact --version 1.32.0
winget install --id suzuki-shunsuke.pinact --exact --version 5.0.2
winget install --id koalaman.shellcheck --exact --version 0.11.0
uv tool install yamllint==1.38.0
uv tool install check-jsonschema==0.39.0Zmiany idą przez Pull Request z zielonym quality-gate. Commit przez hook, bez --no-verify.
MIT, © 2026 CityCouriers.