added readme

Author: dg

readme.md

@@ -0,0 +1,105 @@
+# PHPStan extensions for Nette libraries
+
+![Nette PHPStan Rules](https://github.com/user-attachments/assets/c231ed47-a413-4dd2-81ef-83e52c080427)
+
+[![Downloads this Month](https://img.shields.io/packagist/dm/nette/phpstan-rules.svg)](https://packagist.org/packages/nette/phpstan-rules)
+[![Tests](https://github.com/nette/phpstan-rules/workflows/Tests/badge.svg?branch=master)](https://github.com/nette/phpstan-rules/actions)
+[![Latest Stable Version](https://poser.pugx.org/nette/phpstan-rules/v/stable)](https://github.com/nette/phpstan-rules/releases)
+[![License](https://img.shields.io/badge/license-New%20BSD-blue.svg)](https://github.com/nette/phpstan-rules/blob/master/license.md)
+
+ <!---->
+
+<h3>
+
+Provides custom type extensions and error suppression rules used when analysing Nette libraries with [PHPStan](https://phpstan.org).
+
+</h3>
+
+ <!---->
+
+
+## Installation
+
+Install via Composer:
+
+```shell
+composer require --dev nette/phpstan-rules
+```
+
+Requirements: PHP 8.1 or higher and PHPStan 2.1+.
+
+If you use [phpstan/extension-installer](https://github.com/phpstan/extension-installer), the extension is registered automatically. Otherwise add to your `phpstan.neon`:
+
+```neon
+includes:
+    - vendor/nette/phpstan-rules/extension.neon
+```
+
+ <!---->
+
+## What's Included
+
+ <!---->
+
+### Narrow Return Types
+
+Removes `|false` from return types of native PHP functions and methods where `false` is trivial or outdated. For example, `getcwd()` returns `string|false`, but on modern systems `false` is unrealistic. This extension narrows it to `string`.
+
+Covered functions include `getcwd`, `json_encode`, `preg_match`, `preg_split`, `hash`, `explode`, `array_combine`, and [many more](extension-narrowReturnType.neon).
+
+```php
+// Without extension: string|false
+// With extension: non-empty-string
+$cwd = getcwd();
+```
+
+ <!---->
+
+### Type Validation Call Ignore
+
+Suppresses `expr.resultUnused` for the runtime type validation pattern commonly used in Nette:
+
+```php
+/** @param string[] $items */
+public function setItems(array $items): void
+{
+    (function (string ...$items) {})(...$items);
+}
+```
+
+PHPStan normally reports the closure call result as unused. This extension recognizes the pattern (empty closure body, all parameters variadic with type hints) and ignores the error.
+
+ <!---->
+
+### Type Assertion Testing Helper
+
+The package also provides `Nette\PHPStan\Tester\TypeAssert` for testing type inference in Nette packages using [Nette Tester](https://tester.nette.org):
+
+```php
+use Nette\PHPStan\Tester\TypeAssert;
+
+// Verify assertType() calls in a data file
+TypeAssert::assertTypes(__DIR__ . '/data/types.php', [__DIR__ . '/../extension.neon']);
+
+// Verify PHPStan reports no errors on a file
+TypeAssert::assertNoErrors(__DIR__ . '/data/clean.php', [__DIR__ . '/../extension.neon']);
+```
+
+The data file uses `assertType()` from PHPStan:
+
+```php
+use function PHPStan\Testing\assertType;
+
+assertType('non-empty-string', getcwd());
+assertType('string', Normalizer::normalize('foo'));
+```
+
+ <!---->
+
+## [Support Me](https://github.com/sponsors/dg)
+
+Do you like Nette? Are you looking forward to the new features?
+
+[![Buy me a coffee](https://files.nette.org/icons/donation-3.svg)](https://github.com/sponsors/dg)
+
+Thank you!