ci(config): Add YAML formatter configuration and generate rule documentation

- Introduce .yamlfmt.yml with formatting rules to ensure consistent YAML files
- Add rule-doc-generator script for automated rule documentation generation
- Create peck.json preset for Laravel-specific ignore words
- Update composer.json to include rule-doc commands and dependencies for documentation and Rector categorization

Signed-off-by: guanguans <ityaozm@gmail.com>

Author: guanguans

.yamlfmt.yml

@@ -0,0 +1,8 @@
+formatter:
+  type: basic
+  eof_newline: true
+  retain_line_breaks: true
+  retain_line_breaks_single: true
+  scan_folded_as_literal: true
+  trim_trailing_whitespace: true
+

composer.json

@@ -172,6 +172,7 @@
             "@composer-dependency-analyser",
             "@test",
             "@phpstan",
+            "@rule-doc-rector-generate",
             "@rector-dry-run"
         ],
         "class-leak": "@php ./vendor/bin/class-leak --ansi -v",
@@ -271,6 +272,12 @@
         "release-minor-dry-run": "@release-minor --dry-run",
         "release-patch": "@release patch",
         "release-patch-dry-run": "@release-patch --dry-run",
+        "rule-doc": [
+            "@putenvs",
+            "$PHP82 rule-doc-generator --ansi -vv"
+        ],
+        "rule-doc-rector-generate": "@rule-doc generate src/Support/Rectors/ --output-file=src/Support/Rectors/rector-rules-overview.md --categorize=rector",
+        "rule-doc-rector-validate": "@rule-doc validate src/Support/Rectors/",
         "sk": "@php ./vendor/bin/swiss-knife --ansi -v",
         "sk-check-commented-code": "@sk check-commented-code ./config ./src --line-limit=5",
         "sk-check-conflicts": "@sk check-conflicts ./config ./src",

peck.json

@@ -0,0 +1,9 @@
+{
+    "preset": "laravel",
+    "ignore": {
+        "words": [
+            "php"
+        ],
+        "paths": []
+    }
+}

rule-doc-generator

@@ -0,0 +1,19 @@
+#!/usr/bin/env php
+<?php
+
+declare(strict_types=1);
+
+/**
+ * Copyright (c) 2021-2025 guanguans<ityaozm@gmail.com>
+ *
+ * For the full copyright and license information, please view
+ * the LICENSE file that was distributed with this source code.
+ *
+ * @see https://github.com/guanguans/laravel-skeleton
+ */
+
+namespace RuleDocGenerator202408;
+
+require __DIR__.'/vendor/autoload.php';
+
+require __DIR__.'/vendor-bin/common/vendor/symplify/rule-doc-generator/bin/rule-doc-generator.php';

src/Support/Rectors/AddHasOptionsDocCommentRector.php

@@ -25,14 +25,15 @@
 use Rector\BetterPhpDocParser\PhpDocInfo\PhpDocInfoFactory;
 use Rector\Comments\NodeDocBlock\DocBlockUpdater;
 use Rector\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\Contract\DocumentedRuleInterface;
 use Symplify\RuleDocGenerator\Exception\PoorDocumentationException;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
 /**
  * @internal
  */
-final class AddHasOptionsDocCommentRector extends AbstractRector
+final class AddHasOptionsDocCommentRector extends AbstractRector implements DocumentedRuleInterface
 {
     public function __construct(
         private readonly DocBlockUpdater $docBlockUpdater,

src/Support/Rectors/AddSoarOptionsDocCommentRector.php

@@ -19,14 +19,15 @@
 use PhpParser\Node\ArrayItem;
 use Rector\PhpParser\Node\Value\ValueResolver;
 use Rector\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\Contract\DocumentedRuleInterface;
 use Symplify\RuleDocGenerator\Exception\PoorDocumentationException;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
 /**
  * @internal
  */
-final class AddSoarOptionsDocCommentRector extends AbstractRector
+final class AddSoarOptionsDocCommentRector extends AbstractRector implements DocumentedRuleInterface
 {
     public function __construct(
         private readonly ValueResolver $valueResolver

src/Support/Rectors/SimplifyListIndexRector.php

@@ -20,14 +20,15 @@
 use PhpParser\Node\Scalar\Int_;
 use Rector\PhpParser\Node\Value\ValueResolver;
 use Rector\Rector\AbstractRector;
+use Symplify\RuleDocGenerator\Contract\DocumentedRuleInterface;
 use Symplify\RuleDocGenerator\Exception\PoorDocumentationException;
 use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
 use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;
 
 /**
  * @internal
  */
-final class SimplifyListIndexRector extends AbstractRector
+final class SimplifyListIndexRector extends AbstractRector implements DocumentedRuleInterface
 {
     public function __construct(
         private readonly ValueResolver $valueResolver

src/Support/Rectors/rector-rules-overview.md

@@ -0,0 +1,66 @@
+# 3 Rules Overview
+
+## AddHasOptionsDocCommentRector
+
+Add has options doc comment
+
+- class: [`Guanguans\SoarPHP\Support\Rectors\AddHasOptionsDocCommentRector`](AddHasOptionsDocCommentRector.php)
+
+```diff
++/**
++ * @method \Guanguans\SoarPHP\Soar exceptVerbose() // Verbose
++ * @method \Guanguans\SoarPHP\Soar exceptVersion() // Print version info
++ * @method \Guanguans\SoarPHP\Soar exceptHelp() // Help
++ *
++ * @mixin \Guanguans\SoarPHP\Soar
++ */
+ trait HasOptions
+ {
+ }
+```
+
+<br>
+
+## AddSoarOptionsDocCommentRector
+
+Add soar options doc comment
+
+- class: [`Guanguans\SoarPHP\Support\Rectors\AddSoarOptionsDocCommentRector`](AddSoarOptionsDocCommentRector.php)
+
+```diff
+ return [
++     // AllowCharsets (default "utf8,utf8mb4")
+     '-allow-charsets' => [
+         0 => 'utf8',
+         1 => 'utf8mb4',
+     ],
++
++     // AllowCollates
+     '-allow-collates' => [
+     ],
++
++     // AllowDropIndex, 允许输出删除重复索引的建议
+     '-allow-drop-index' => false,
+ ];
+```
+
+<br>
+
+## SimplifyListIndexRector
+
+Simplify list index
+
+- class: [`Guanguans\SoarPHP\Support\Rectors\SimplifyListIndexRector`](SimplifyListIndexRector.php)
+
+```diff
+ [
+-    0 => 'delimiter',
+-    1 => 'orderbynull',
+-    2 => 'groupbyconst',
++    'delimiter',
++    'orderbynull',
++    'groupbyconst',
+ ]
+```
+
+<br>

tests/Pest.php

@@ -30,7 +30,13 @@
     ->beforeEach(function (): void {})
     ->afterEach(function (): void {})
     ->afterAll(function (): void {})
-    ->in(__DIR__, __DIR__.'/Feature', __DIR__.'/Unit');
+    ->in(
+        __DIR__,
+        __DIR__.'/Arch/',
+        __DIR__.'/Feature/',
+        __DIR__.'/Integration/',
+        __DIR__.'/Unit/'
+    );
 /*
 |--------------------------------------------------------------------------
 | Expectations

vendor-bin/common/composer.json

@@ -0,0 +1,5 @@
+{
+    "require-dev": {
+        "symplify/rule-doc-generator": "^12.2"
+    }
+}