Skip to content
CityCouriersPublic

About

pc: lokalne bramki jakosci PHP (PHPStan, PHPMD, Pint/PHPCS, testy, mutacje) jako pakiet Composera. MIT.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Repository files navigation

citycouriers/pc

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, silnik pc run i 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ć.

Użycie

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 }
}

Zasady

  • 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).

Dokumentacja

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

Rozwój

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

Zmiany idą przez Pull Request z zielonym quality-gate. Commit przez hook, bez --no-verify.

Licencja

MIT, © 2026 CityCouriers.

About

pc: lokalne bramki jakosci PHP (PHPStan, PHPMD, Pint/PHPCS, testy, mutacje) jako pakiet Composera. MIT.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Used by

Contributors

Languages