coding-standard icon indicating copy to clipboard operation
coding-standard copied to clipboard

Irresolvable conflict between DocCommentSpacing rules since 8.14.0

Open TravisCarden opened this issue 1 year ago • 5 comments

I got a dependabot PR today that updates slevomat/coding-standard from 8.13.4 to 8.14.1, and I'm getting two new failures on the same code and configuration that was passing before. They both claim to be fixable, but running phpcbf yields "FAILED TO FIX". Here are the details:

Error Output

$ phpcs -s

FILE: php-tuf/composer-stager/src/API/Precondition/Service/PreconditionInterface.php
----------------------------------------------------------------------------------------------------------------------------------------------------------
FOUND 2 ERRORS AFFECTING 2 LINES
----------------------------------------------------------------------------------------------------------------------------------------------------------
 41 | ERROR | [x] Expected 1 line between description and annotations, found 0.
    |       |     (SlevomatCodingStandard.Commenting.DocCommentSpacing.IncorrectLinesCountBetweenDescriptionAndAnnotations)
 44 | ERROR | [x] Expected 0 lines after last content, found 1. (SlevomatCodingStandard.Commenting.DocCommentSpacing.IncorrectLinesCountAfterLastContent)
----------------------------------------------------------------------------------------------------------------------------------------------------------
PHPCBF CAN FIX THE 2 MARKED SNIFF VIOLATIONS AUTOMATICALLY
----------------------------------------------------------------------------------------------------------------------------------------------------------

Code in Question

https://github.com/php-tuf/composer-stager/blob/d74d77059d5b4d6abe3558703a80f534162491d2/src/API/Precondition/Service/PreconditionInterface.php#L34-L52

    /**
     * Gets a short status message.
     *
     * This reflects the actual status of the precondition at runtime and may
     * include details for resolving an unfulfilled precondition, e.g., "The
     * example dependency is ready," or if unfulfilled, "The example dependency
     * cannot be found. Make sure it's installed." If the precondition has
     * unfulfilled leaves, the status message from the first one will be returned.
     *
     * @param int $timeout
     *   An optional process timeout (maximum runtime) in seconds. If set to
     *   zero (0), no time limit is imposed.
     */
    public function getStatusMessage(
        PathInterface $activeDir,
        PathInterface $stagingDir,
        ?PathListInterface $exclusions = null,
        int $timeout = ProcessInterface::DEFAULT_TIMEOUT,
    ): TranslatableInterface;

Configuration

https://github.com/php-tuf/composer-stager/blob/d74d77059d5b4d6abe3558703a80f534162491d2/phpcs.xml.dist#L101C50-L120

    <rule ref="SlevomatCodingStandard.Commenting.DocCommentSpacing"><properties>
        <property name="annotationsGroups" type="array">
            <element value="@file"/>
            <element value="@coversDefaultClass"/>
            <element value="@covers,@coversNothing"/>
            <element value="@uses"/>
            <element value="@dataProvider"/>
            <element value="@property"/>
            <element value="@var"/>
            <element value="@param"/>
            <element value="@return"/>
            <element value="@throws"/>
            <element value="@see"/>
            <element value="@package"/>
            <element value="@api,@internal"/>
            <element value="@todo"/>
            <element value="@noinspection,@SuppressWarnings"/>
        </property>
        <property name="linesCountBetweenDifferentAnnotationsTypes" value="1"/>
    </properties></rule>

Observations

The problems seems to have something to do with the quotation marks (") in the docblock. The simplest test case I've been able to construct to reproduce the problem involves four or more of them on different lines and at least one @param tag (below). It doesn't seem to matter whether there are line breaks or other characters in the text as long as there are at least four quotation marks on at least four lines. As I add @param tags the errors multiply.

    /**
     * "
     * "
     * "
     * "
     *
     * @param int $timeout
     *   X
     */
    public function getStatusMessage(
        PathInterface $activeDir,
        PathInterface $stagingDir,
        ?PathListInterface $exclusions = null,
        int $timeout = ProcessInterface::DEFAULT_TIMEOUT,
    ): TranslatableInterface;

If it's helpful for testing/debugging, you can checkout the affected branch of my repo at https://github.com/php-tuf/composer-stager/tree/develop:

git clone [email protected]:php-tuf/composer-stager.git

TravisCarden avatar Oct 09 '23 16:10 TravisCarden

Update: After some more investigation, it looks like the root cause is actually in phpstan/phpdoc-parser. On its v1.23.0 my scans pass. On v1.23.1 they fail as detailed above.

What's the proper way to proceed given the fact that the problem isn't with slevomat/coding-standard itself? Move this issue to phpstan/phpdoc-parser? Create a new one there?

TravisCarden avatar Oct 09 '23 17:10 TravisCarden

Cc @ondrejmirtes

kukulich avatar Oct 09 '23 18:10 kukulich

Just a friendly update that this issue persists. It came up again in another Dependabot PR: https://github.com/php-tuf/composer-stager/pull/309.

TravisCarden avatar Dec 11 '23 15:12 TravisCarden

This is a bug in phpstan/phpdoc-parser which I don't know yet how to fix.

The workaround is to remove " from the PHPDoc. At least those that span multiple lines.

ondrejmirtes avatar Dec 11 '23 16:12 ondrejmirtes

Okay, thanks, @ondrejmirtes.

TravisCarden avatar Dec 13 '23 01:12 TravisCarden