Merge pull request #4 from jackd248/align-rule

refactor(!): remove 'package' annotation from DocBlock examples

Author: jackd248

.gitignore

@@ -3,6 +3,7 @@
 /.php-cs-fixer.cache
 /.phpunit.result.cache
 /.build
+/coverage-report
 /php-cs-fixer.xml
 /phpstan.xml
 /site

README.md

@@ -36,7 +36,6 @@ class MyClass
  * MyClass.
  *
  * @author Your Name <your@email.org>
- * @package MyPackage
  */
 class MyClass
 {
@@ -58,6 +57,9 @@ composer require --dev konradmichalik/php-doc-block-header-fixer
 
 Add the PHP-CS-Fixer rule in your `.php-cs-fixer.php` file:
 
+> [!NOTE]
+> This fixer is compatible with standard PHP-CS-Fixer rules. It avoids adding annotations that conflict with rules like `phpdoc_no_package` and follows spacing conventions compatible with `phpdoc_separation`.
+
 ```php
 <?php
 // ...
@@ -71,7 +73,6 @@ return (new PhpCsFixer\Config())
             'annotations' => [
                 'author' => 'Konrad Michalik <hej@konradmichalik.dev>',
                 'license' => 'GPL-3.0-or-later',
-                'package' => 'PhpDocBlockHeaderFixer',
             ],
             'preserve_existing' => true,
             'separate' => 'none',
@@ -96,7 +97,6 @@ return (new PhpCsFixer\Config())
             [
                 'author' => 'Konrad Michalik <hej@konradmichalik.dev>',
                 'license' => 'GPL-3.0-or-later',
-                'package' => 'PhpDocBlockHeaderFixer',
             ],
             preserveExisting: true,
             separate: \KonradMichalik\PhpDocBlockHeaderFixer\Enum\Separate::None,

composer.json

@@ -1,6 +1,6 @@
 {
 	"name": "konradmichalik/php-doc-block-header-fixer",
-	"description": "",
+	"description": "This package contains a PHP-CS-Fixer rule to automatically fix the class header regarding PHP DocBlocks.",
 	"license": "GPL-3.0-or-later",
 	"type": "library",
 	"authors": [

src/Rules/DocBlockHeaderFixer.php

@@ -79,7 +79,7 @@ public function getConfigurationDefinition(): FixerConfigurationResolverInterfac
                 ->getOption(),
             (new FixerOptionBuilder('separate', 'Separate the comment'))
                 ->setAllowedValues(Separate::getList())
-                ->setDefault(Separate::Both->value)
+                ->setDefault(Separate::None->value)
                 ->getOption(),
             (new FixerOptionBuilder('add_class_name', 'Add class name before annotations'))
                 ->setAllowedTypes(['bool'])
@@ -202,7 +202,7 @@ private function replaceDocBlock(Tokens $tokens, int $docBlockIndex, array $anno
      */
     private function insertNewDocBlock(Tokens $tokens, int $classIndex, array $annotations, string $className): void
     {
-        $separate = $this->resolvedConfiguration['separate'] ?? 'both';
+        $separate = $this->resolvedConfiguration['separate'] ?? 'none';
         $insertIndex = $this->findInsertPosition($tokens, $classIndex);
 
         $tokensToInsert = [];
@@ -216,9 +216,14 @@ private function insertNewDocBlock(Tokens $tokens, int $classIndex, array $annot
         $docBlock = $this->buildDocBlock($annotations, $className);
         $tokensToInsert[] = new Token([T_DOC_COMMENT, $docBlock]);
 
-        // Add separation after comment if needed
+        // For compatibility with no_blank_lines_after_phpdoc, only add bottom separation when 'separate' is not 'none'
+        // This prevents conflicts with PHP-CS-Fixer rules that manage DocBlock spacing
         if (in_array($separate, ['bottom', 'both'], true)) {
-            $tokensToInsert[] = new Token([T_WHITESPACE, "\n"]);
+            // Check if there's already whitespace after the class declaration
+            $nextToken = $tokens[$classIndex] ?? null;
+            if (null !== $nextToken && !$nextToken->isWhitespace()) {
+                $tokensToInsert[] = new Token([T_WHITESPACE, "\n"]);
+            }
         }
 
         $tokens->insertAt($insertIndex, $tokensToInsert);
@@ -296,7 +301,7 @@ private function buildDocBlock(array $annotations, string $className): string
         if ($addClassName && !empty($className)) {
             $docBlock .= " * {$className}.\n";
 
-            // Add empty line after class name if there are annotations
+            // Add empty line after class name if there are annotations - compatible with phpdoc_separation
             if (!empty($annotations)) {
                 $docBlock .= " *\n";
             }

tests/src/Generators/DocBlockHeaderTest.php

@@ -125,7 +125,6 @@ public function testValidateAnnotationsWithValidKeys(): void
             'license' => 'MIT',
             'version' => '1.0.0',
             'since' => '1.0.0',
-            'package' => 'MyPackage',
             'subpackage' => 'SubPackage',
             'see' => 'https://example.com',
             'link' => 'https://example.com',

tests/src/Rules/DocBlockHeaderFixerTest.php

@@ -97,10 +97,9 @@ public function testBuildDocBlockWithMultipleAnnotations(): void
         $result = $method->invoke($this->fixer, [
             'author' => 'John Doe <john@example.com>',
             'license' => 'MIT',
-            'package' => 'MyPackage',
         ], '');
 
-        $expected = "/**\n * @author John Doe <john@example.com>\n * @license MIT\n * @package MyPackage\n */";
+        $expected = "/**\n * @author John Doe <john@example.com>\n * @license MIT\n */";
         self::assertSame($expected, $result);
     }