Adding a rule for doc blocks containing specifications

Author: Florian Krämer

data/SpecificationDocblock/InvalidMissingPeriodsClass.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\SpecificationDocblock;
+
+/**
+ * Specification:
+ *
+ * - Removes an item from the recommendation engine
+ * - Updates the cache accordingly
+ */
+class InvalidMissingPeriodsClass
+{
+    public function execute(): void
+    {
+    }
+}
+

data/SpecificationDocblock/InvalidMultiLineNoPeriodClass.php

@@ -0,0 +1,20 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\SpecificationDocblock;
+
+/**
+ * Specification:
+ *
+ * - Removes an item from the recommendation engine
+ *   and updates all related caches
+ * - Validates the input data
+ */
+class InvalidMultiLineNoPeriodClass
+{
+    public function execute(): void
+    {
+    }
+}
+

data/SpecificationDocblock/InvalidSpecificationNoBlankLineClass.php

@@ -0,0 +1,17 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\SpecificationDocblock;
+
+/**
+ * Specification:
+ * - Missing blank line after header.
+ */
+class InvalidSpecificationNoBlankLineClass
+{
+    public function execute(): void
+    {
+    }
+}
+

data/SpecificationDocblock/InvalidSpecificationNoListItemClass.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\SpecificationDocblock;
+
+/**
+ * Specification:
+ *
+ * This has no list items.
+ */
+class InvalidSpecificationNoListItemClass
+{
+    public function execute(): void
+    {
+    }
+}
+

data/SpecificationDocblock/MissingDocblockClass.php

@@ -0,0 +1,13 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\SpecificationDocblock;
+
+class MissingDocblockClass
+{
+    public function execute(): void
+    {
+    }
+}
+

data/SpecificationDocblock/MissingSpecificationHeaderClass.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\SpecificationDocblock;
+
+/**
+ * This is just a regular docblock.
+ *
+ * - Some item here.
+ */
+class MissingSpecificationHeaderClass
+{
+    public function execute(): void
+    {
+    }
+}
+

data/SpecificationDocblock/README.md

@@ -0,0 +1,116 @@
+# Specification Docblock Rule
+
+This directory contains test data for the `ClassMustHaveSpecificationDocblockRule`.
+
+## Rule Configuration Example
+
+```neon
+# phpstan.neon
+services:
+    -
+        class: Phauthentic\PHPStanRules\Architecture\ClassMustHaveSpecificationDocblockRule
+        arguments:
+            patterns:
+                - '/.*Facade$/'                         # All classes ending with "Facade"
+                - '/.*Command$/'                        # All classes ending with "Command"
+                - '/.*Handler$/'                        # All classes ending with "Handler"
+            specificationHeader: 'Specification:'       # Optional: customize the header
+            requireBlankLineAfterHeader: true           # Optional: require blank line (default: true)
+            requireListItemsEndWithPeriod: false        # Optional: require periods (default: false)
+        tags:
+            - phpstan.rules.rule
+```
+
+## Configuration Options
+
+- `patterns`: Array of regex patterns to match class names (required)
+- `specificationHeader`: Header text to look for (default: `'Specification:'`)
+- `requireBlankLineAfterHeader`: Require blank line after header (default: `true`)
+- `requireListItemsEndWithPeriod`: Require list items end with period (default: `false`)
+
+## Valid Specification Format
+
+### Minimum Required Format
+```php
+/**
+ * Specification:
+ *
+ * - Removes an item from the recommendation engine.
+ */
+class MyClass {}
+```
+
+### Multi-Line List Items
+List items can span multiple lines:
+```php
+/**
+ * Specification:
+ *
+ * - Removes an item from the recommendation engine
+ *   and updates all related caches including user
+ *   preferences and global recommendations.
+ * - Validates the input data before processing
+ *   and throws an exception if validation fails.
+ */
+class MyClass {}
+```
+
+### With Annotations
+```php
+/**
+ * Specification:
+ *
+ * - Removes an item from the recommendation engine.
+ *
+ * @throws \Exception
+ */
+class MyClass {}
+```
+
+### With Additional Description and Annotations
+```php
+/**
+ * Specification:
+ *
+ * - Removes an item from the recommendation engine.
+ * - Updates the cache accordingly.
+ *
+ * Some additional description goes here.
+ *
+ * @throws \Exception
+ * @return void
+ */
+class MyClass {}
+```
+
+## Invalid Formats
+
+### Missing Specification Header
+```php
+/**
+ * This is just a regular docblock.
+ *
+ * - Some item here.
+ */
+class MyClass {} // ERROR
+```
+
+### Missing Blank Line After Header
+```php
+/**
+ * Specification:
+ * - Missing blank line after header.
+ */
+class MyClass {} // ERROR
+```
+
+### Missing List Items
+```php
+/**
+ * Specification:
+ *
+ * This has no list items.
+ */
+class MyClass {} // ERROR
+```
+

data/SpecificationDocblock/ValidCustomHeaderClass.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\SpecificationDocblock;
+
+/**
+ * Requirements:
+ *
+ * - Removes an item from the recommendation engine.
+ * - Updates the cache accordingly.
+ */
+class ValidCustomHeaderClass
+{
+    public function execute(): void
+    {
+    }
+}
+

data/SpecificationDocblock/ValidMultiLineComplexClass.php

@@ -0,0 +1,26 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\SpecificationDocblock;
+
+/**
+ * Specification:
+ *
+ * - Removes an item from the recommendation engine
+ *   and updates all related caches including:
+ *     - User preferences cache
+ *     - Global recommendations cache
+ *   This ensures consistency across the system.
+ * - Validates the input data before processing.
+ *
+ * @param array $data
+ * @throws \InvalidArgumentException
+ */
+class ValidMultiLineComplexClass
+{
+    public function execute(): void
+    {
+    }
+}
+

data/SpecificationDocblock/ValidMultiLineListItemClass.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace App\SpecificationDocblock;
+
+/**
+ * Specification:
+ *
+ * - Removes an item from the recommendation engine
+ *   and updates all related caches.
+ * - Validates the input data before processing
+ *   and throws an exception if validation fails.
+ */
+class ValidMultiLineListItemClass
+{
+    public function execute(): void
+    {
+    }
+}
+