Add inner-bucket tag ordering to DocBlockTagOrderSniff

tests/PhpCollective/Sniffs/Commenting/DocBlockTagOrderSniffTest.php

@@ -81,4 +81,83 @@ public function testDocBlockTagOrderNormalizesBlankLineSeparators(): void
 
         $this->prefix = null;
     }
+
+    /**
+     * Empty pattern list for a tag means "alphabetize everything in this bucket."
+     * Typical recipe for @property association lists.
+     *
+     * @return void
+     */
+    public function testDocBlockTagOrderInnerOrderProperty(): void
+    {
+        $this->prefix = 'inner-property.';
+
+        $sniff = new DocBlockTagOrderSniff();
+        $sniff->innerOrder = ['@property' => ''];
+
+        $this->assertSnifferCanFixErrors($sniff, 1);
+
+        $this->prefix = null;
+    }
+
+    /**
+     * @method CRUD recipe: prefix-priority with alphabetical tiebreak,
+     * unmatched custom methods float to the bottom alphabetically.
+     *
+     * @return void
+     */
+    public function testDocBlockTagOrderInnerOrderMethodCrud(): void
+    {
+        $this->prefix = 'inner-method.';
+
+        $sniff = new DocBlockTagOrderSniff();
+        $sniff->innerOrder = [
+            '@method' => 'newEmptyEntity,newEntity,newEntities,get,findOrCreate,find*,patchEntity,patchEntities,save,saveOrFail,saveMany*,delete,deleteOrFail,deleteMany*',
+        ];
+
+        $this->assertSnifferCanFixErrors($sniff, 1);
+
+        $this->prefix = null;
+    }
+
+    /**
+     * Edge-case shapes for @method: generic / union return types, `static` modifier,
+     * missing return type, trailing-bareword malformed line.
+     *
+     * @return void
+     */
+    public function testDocBlockTagOrderInnerOrderMethodEdges(): void
+    {
+        $this->prefix = 'inner-method-edges.';
+
+        $sniff = new DocBlockTagOrderSniff();
+        $sniff->innerOrder = [
+            '@method' => 'newEmptyEntity,newEntity,newEntities,get,findOrCreate,find*,patchEntity,patchEntities,save,saveOrFail,saveMany*,delete,deleteOrFail,deleteMany*',
+        ];
+
+        $this->assertSnifferCanFixErrors($sniff, 1);
+
+        $this->prefix = null;
+    }
+
+    /**
+     * Combined: bucket reordering + inner ordering for both @method and @property
+     * applied in one fixer pass.
+     *
+     * @return void
+     */
+    public function testDocBlockTagOrderInnerOrderCombined(): void
+    {
+        $this->prefix = 'inner-combined.';
+
+        $sniff = new DocBlockTagOrderSniff();
+        $sniff->innerOrder = [
+            '@method' => 'newEmptyEntity,newEntity,newEntities,get,findOrCreate,find*,patchEntity,patchEntities,save,saveOrFail,saveMany*,delete,deleteOrFail,deleteMany*',
+            '@property' => '',
+        ];
+
+        $this->assertSnifferCanFixErrors($sniff, 2);
+
+        $this->prefix = null;
+    }
 }

tests/_data/DocBlockTagOrder/inner-combined.after.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types = 1);
+
+namespace PhpCollective;
+
+/**
+ * Class with both bucket-misordering and within-bucket misordering.
+ *
+ * @extends \BaseTable<array{Slugged: \Behavior}>
+ * @property \Foo $Boards
+ * @property \Foo $StaffMembers
+ * @method \Foo newEmptyEntity()
+ * @method \Foo get(mixed $pk)
+ * @method \Foo save(\Foo $entity)
+ * @mixin \BehaviorOne
+ * @mixin \BehaviorTwo
+ */
+class FixMe
+{
+}

tests/_data/DocBlockTagOrder/inner-combined.before.php

@@ -0,0 +1,19 @@
+<?php declare(strict_types = 1);
+
+namespace PhpCollective;
+
+/**
+ * Class with both bucket-misordering and within-bucket misordering.
+ *
+ * @method \Foo save(\Foo $entity)
+ * @property \Foo $StaffMembers
+ * @mixin \BehaviorOne
+ * @method \Foo newEmptyEntity()
+ * @property \Foo $Boards
+ * @extends \BaseTable<array{Slugged: \Behavior}>
+ * @method \Foo get(mixed $pk)
+ * @mixin \BehaviorTwo
+ */
+class FixMe
+{
+}

tests/_data/DocBlockTagOrder/inner-method-edges.after.php

@@ -0,0 +1,18 @@
+<?php declare(strict_types = 1);
+
+namespace PhpCollective;
+
+/**
+ * Class with @method lines exercising the type-expression walker.
+ *
+ * @method static \Foo newEmptyEntity()
+ * @method get(mixed $primaryKey)
+ * @method \Foo|null findOrCreate(array $search)
+ * @method \Foo\Container<array{a: int, b: string}> save(\Foo $entity)
+ * @method \Cake\Datasource\ResultSetInterface<\Foo>|false saveMany(iterable $entities)
+ * @method \Foo customMethod(\Foo $entity)
+ * @method \Foo somethingMalformed
+ */
+class FixMe
+{
+}

tests/_data/DocBlockTagOrder/inner-method-edges.before.php

@@ -0,0 +1,18 @@
+<?php declare(strict_types = 1);
+
+namespace PhpCollective;
+
+/**
+ * Class with @method lines exercising the type-expression walker.
+ *
+ * @method \Foo|null findOrCreate(array $search)
+ * @method static \Foo newEmptyEntity()
+ * @method \Cake\Datasource\ResultSetInterface<\Foo>|false saveMany(iterable $entities)
+ * @method get(mixed $primaryKey)
+ * @method \Foo\Container<array{a: int, b: string}> save(\Foo $entity)
+ * @method \Foo somethingMalformed
+ * @method \Foo customMethod(\Foo $entity)
+ */
+class FixMe
+{
+}

tests/_data/DocBlockTagOrder/inner-method.after.php

@@ -0,0 +1,23 @@
+<?php declare(strict_types = 1);
+
+namespace PhpCollective;
+
+/**
+ * Class with scrambled @method block (typical IDE-helper output).
+ *
+ * @method \Foo\Entity newEmptyEntity()
+ * @method \Foo\Entity newEntity(array $data, array $options = [])
+ * @method static array<\Foo\Entity> newEntities(array $data, array $options = [])
+ * @method \Foo\Entity get(mixed $primaryKey, array $finder = 'all')
+ * @method \Foo\Entity findOrCreate(\Cake\ORM\Query\SelectQuery|callable|array $search, ?callable $callback = null)
+ * @method \Foo\Entity patchEntity(\Foo\Entity $entity, array $data, array $options = [])
+ * @method \Foo\Entity save(\Foo\Entity $entity, array $options = [])
+ * @method \Foo\Entity|false saveMany(iterable $entities, array $options = [])
+ * @method \Foo\Entity saveManyOrFail(iterable $entities, array $options = [])
+ * @method bool delete(\Foo\Entity $entity, array $options = [])
+ * @method array<\Foo\Entity> deleteMany(iterable $entities, array $options = [])
+ * @method \Foo\Entity customDomainMethod(\Foo\Entity $entity)
+ */
+class FixMe
+{
+}

tests/_data/DocBlockTagOrder/inner-method.before.php

@@ -0,0 +1,23 @@
+<?php declare(strict_types = 1);
+
+namespace PhpCollective;
+
+/**
+ * Class with scrambled @method block (typical IDE-helper output).
+ *
+ * @method \Foo\Entity save(\Foo\Entity $entity, array $options = [])
+ * @method \Foo\Entity get(mixed $primaryKey, array $finder = 'all')
+ * @method \Foo\Entity newEntity(array $data, array $options = [])
+ * @method \Foo\Entity newEmptyEntity()
+ * @method \Foo\Entity patchEntity(\Foo\Entity $entity, array $data, array $options = [])
+ * @method \Foo\Entity findOrCreate(\Cake\ORM\Query\SelectQuery|callable|array $search, ?callable $callback = null)
+ * @method \Foo\Entity|false saveMany(iterable $entities, array $options = [])
+ * @method \Foo\Entity saveManyOrFail(iterable $entities, array $options = [])
+ * @method bool delete(\Foo\Entity $entity, array $options = [])
+ * @method array<\Foo\Entity> deleteMany(iterable $entities, array $options = [])
+ * @method static array<\Foo\Entity> newEntities(array $data, array $options = [])
+ * @method \Foo\Entity customDomainMethod(\Foo\Entity $entity)
+ */
+class FixMe
+{
+}

tests/_data/DocBlockTagOrder/inner-property.after.php

@@ -0,0 +1,17 @@
+<?php declare(strict_types = 1);
+
+namespace PhpCollective;
+
+/**
+ * Class with unsorted @property association list.
+ *
+ * @property \Foo $Boards
+ * @property \Foo $MenuItems
+ * @property \Foo $StaffMemberCarCharges
+ * @property \Foo $StaffMembersProjects
+ * @property \Foo $StaffMembersWorkTimes
+ * @property \Foo $TimesheetUploads
+ */
+class FixMe
+{
+}

tests/_data/DocBlockTagOrder/inner-property.before.php

@@ -0,0 +1,17 @@
+<?php declare(strict_types = 1);
+
+namespace PhpCollective;
+
+/**
+ * Class with unsorted @property association list.
+ *
+ * @property \Foo $StaffMembersWorkTimes
+ * @property \Foo $Boards
+ * @property \Foo $StaffMemberCarCharges
+ * @property \Foo $TimesheetUploads
+ * @property \Foo $MenuItems
+ * @property \Foo $StaffMembersProjects
+ */
+class FixMe
+{
+}