Updating a node comments removes empty lines between the comment block and the node

[leandr]

Bug Report

Subject	Details
Rector version	v0.14.8
PHP version	8.1.12

When you do something with a node's comments, the procedure removes empty lines between the comment block and the node, so sometimes it breaks the structure of the commented code and makes it harder to read.

Minimal PHP Code Causing Issue

Custom rule:

<?php

namespace Bumble\RefactoringTools\Rector\CustomRules;

use PhpParser\Node;
use PhpParser\Comment;
use Rector\Core\Rector\AbstractRector;
use Rector\NodeTypeResolver\Node\AttributeKey;
use Symplify\RuleDocGenerator\ValueObject\CodeSample\CodeSample;
use Symplify\RuleDocGenerator\ValueObject\RuleDefinition;

class TestRector extends AbstractRector
{
    public function getRuleDefinition(): RuleDefinition
    {
        return new RuleDefinition('Hello!', [
            new CodeSample(
                <<<'PHP'
return;
PHP,
                <<<'PHP'
return;
PHP,
            ),
        ]);
    }

    public function getNodeTypes(): array
    {
        return [
            Node::class,
        ];
    }

    public function refactor(Node $node): ?Node
    {
        /** @var Comment[] $comments */
        $comments = $node->getAttribute(AttributeKey::COMMENTS);
        if (!$comments) {
            return null;
        }

        $newComments = [];
        foreach ($comments as $comment) {
            // do something with comments
            $newComments[] = new Comment($comment->getText());
        }

        $node->setAttribute(AttributeKey::COMMENTS, $newComments);
        return $node;
    }
}

PHP code to format:

<?php
/**
 * Annotation of the file
 * Needs an empty line after it
 */

namespace TestMe;

/**
 * Class description
 */
class MyClass
{
    /**
     * Go for it
     *
     * @param array $api
     * @return void
     */
    public function myMethod(array $api): void
    {
        // do something
        $myVariable = array_reverse($api);

        // important comment, well highlighted

        // just export the var
        echo var_export($myVariable, true);
    }
}

Actual Result

No empty line before the 'namespace' line, and no empty line after the 'important comment':

<?php
/**
 * Annotation of the file
 * Needs an empty line after it
 */
namespace TestMe;

/**
 * Class description
 */
class MyClass
{
    /**
     * Go for it
     *
     * @param array $api
     * @return void
     */
    public function myMethod(array $api): void
    {
        // do something
        $myVariable = array_reverse($api);

        // important comment, well highlighted
        // just export the var
        echo var_export($myVariable, true);
    }
}

Expected Result

Lines between comments and nodes remain.

<?php
/**
 * Annotation of the file
 * Needs an empty line after it
 */

namespace TestMe;

/**
 * Class description
 */
class MyClass
{
    /**
     * Go for it
     *
     * @param array $api
     * @return void
     */
    public function myMethod(array $api): void
    {
        // do something
        $myVariable = array_reverse($api);

        // important comment, well highlighted

        // just export the var
        echo var_export($myVariable, true);
    }
}

[TomasVotruba]

This is inherited feature from php-parser. See nikic/PHP-Parser#344