From 9bf4e98556e797ee4bcd45f911c1b5d8e6dbfcb0 Mon Sep 17 00:00:00 2001
From: Divarion-D <danil.dmitrievn@gmail.com>
Date: Tue, 23 Jun 2026 22:07:31 +0300
Subject: [PATCH] docs(contributing): document `make phpstan` and baseline
 workflow

Adds a Static Analysis section: how to run PHPStan, that CI fails only on new
issues (committed baseline), not to grow the baseline to hide real problems,
how to regenerate it, and the clear-result-cache caveat after stub/PHPDoc edits.
---
 CONTRIBUTING.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 59adecb1..7e4471f5 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -65,6 +65,37 @@ bash tools/php_syntax_check.sh src/domain/Device/EnigmaService.php
 
 Do not submit PRs with syntax errors — CI will reject them.
 
+## 🔬 Static Analysis (PHPStan)
+
+The project is analysed with **PHPStan** (level 5). There is no Composer — the
+pinned PHAR is downloaded on first run, and a bootstrap registers the project's
+constants/classes (`tools/phpstan/`).
+
+Run the analysis before submitting a PR:
+
+```sh
+make phpstan
+```
+
+This is the same check CI runs. It must report **`[OK] No errors`**.
+
+How the gate works:
+
+- A committed baseline (`phpstan-baseline.neon`) freezes the pre-existing
+  findings, so CI only fails on **new** issues your change introduces — fix
+  those before pushing.
+- The baseline is **not** a list of accepted bugs (most entries are false
+  positives from dynamic DB-row shapes or templates). Do **not** grow it to hide
+  a real problem in new code.
+- If you fix a batch of existing findings, regenerate the (smaller) baseline:
+
+  ```sh
+  make phpstan-baseline
+  ```
+
+- After editing `tools/phpstan/constants.stub.php` or any PHPDoc types, clear the
+  result cache first: `php tools/phpstan/phpstan.phar clear-result-cache`.
+
 ## 🧪 Adding Tests
 
 - Add new PHP tests under `tests/Unit/`.