coding-standard/src/DocBlock/UselessDocBlockCleaner.php at b4a2e50ae5bea559ee77820debac6e2a0e5b2f50 · symplify/coding-standard · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
<?php

declare(strict_types=1);

namespace Symplify\CodingStandard\DocBlock;

use Nette\Utils\Strings;
use PhpCsFixer\Tokenizer\Token;

final class UselessDocBlockCleaner
{
    /**
     * @var string[]
     */
    private const CLEANING_REGEXES = [
        self::TODO_COMMENT_BY_PHPSTORM_REGEX,
        self::TODO_IMPLEMENT_METHOD_COMMENT_BY_PHPSTORM_REGEX,
        self::COMMENT_CONSTRUCTOR_CLASS_REGEX,
        self::CLASS_REPRESENTING_REGEX,

        // must run first
        self::STANDALONE_DOCBLOCK_CLASS_REGEX,
        // then this one
        self::STANDALONE_COMMENT_CLASS_REGEX,
        // then this one
        self::INLINE_COMMENT_CLASS_REGEX,
    ];

    /**
     * @see https://regex101.com/r/5fQJkz/2
     * @var string
     */
    private const TODO_IMPLEMENT_METHOD_COMMENT_BY_PHPSTORM_REGEX = '#\/\/ TODO: Implement .*\(\) method.$#';

    /**
     * @see https://regex101.com/r/zayQpv/1
     * @var string
     */
    private const TODO_COMMENT_BY_PHPSTORM_REGEX = '#\/\/ TODO: Change the autogenerated stub$#';

    /**
     * @see https://regex101.com/r/RzTdFH/4
     * @var string
     */
    private const STANDALONE_DOCBLOCK_CLASS_REGEX = '#(\/\*\*\s+)\*\s+[cC]lass\s+[^\s]*(\s+\*\/)$#';

    /**
     * @see https://regex101.com/r/RzTdFH/4
     * @var string
     */
    private const STANDALONE_COMMENT_CLASS_REGEX = '#\/\/\s+(class|trait|interface)\s+\w+$#i';

    /**
     * @see https://regex101.com/r/RzTdFH/4
     * @var string
     */
    private const INLINE_COMMENT_CLASS_REGEX = '#\s\*\s(class|trait|interface)\s+(\w)+$#i';

    /**
     * @var string
     */
    private const COMMENT_CONSTRUCTOR_CLASS_REGEX = '#^(\/\/|(\s|\*)+)(\s\w+\s)?constructor(\.)?$#i';

    /**
     * @see https://regex101.com/r/1kcgR5/1
     * @var string
     */
    private const DOCTRINE_GENERATED_COMMENT_REGEX = '#^(\/\*{2}\s+?)?(\*|\/\/)\s+This class was generated by the Doctrine ORM\. Add your own custom\r?\n\s+\*\s+repository methods below\.(\s+\*\/)$#';

    /**
     * @var string
     */
    private const CLASS_REPRESENTING_REGEX = '#\s\*\sClass\s+representing\s+([\w]+)$#i';

    public function clearDocTokenContent(Token $currentToken, ?string $classLikeName): string
    {
        $docContent = $currentToken->getContent();

        $cleanedCommentLines = [];

        foreach (explode("\n", $docContent) as $key => $commentLine) {
            if ($this->isClassLikeName($commentLine, $classLikeName)) {
                continue;
            }

            foreach (self::CLEANING_REGEXES as $cleaningRegex) {
                $commentLine = Strings::replace($commentLine, $cleaningRegex);
            }

            $cleanedCommentLines[$key] = $commentLine;
        }

        // remove empty lines
        $cleanedCommentLines = array_filter($cleanedCommentLines);
        $cleanedCommentLines = array_values($cleanedCommentLines);

        // is totally empty?
        if ($this->isEmptyDocblock($cleanedCommentLines)) {
            return '';
        }

        $commentText = implode("\n", $cleanedCommentLines);

        // run multilines regex on final result
        return Strings::replace($commentText, self::DOCTRINE_GENERATED_COMMENT_REGEX);
    }

    /**
     * @param string[] $commentLines
     */
    private function isEmptyDocblock(array $commentLines): bool
    {
        if (count($commentLines) !== 2) {
            return false;
        }

        $startCommentLine = $commentLines[0];
        $endCommentLine = $commentLines[1];

        return $startCommentLine === '/**' && trim($endCommentLine) === '*/';
    }

    private function isClassLikeName(string $commentLine, ?string $classLikeName): bool
    {
        if ($classLikeName === null) {
            return false;
        }

        return trim($commentLine, '* ') === $classLikeName;
    }
}