FqcnMethodSniff::configure() - Code Metrics - Inspection of "Merge remote-tracking branch 'remotes/origin/confi..." - gskema/phpcs-type-sniff - Measure and Improve Code Quality continuously with Scrutinizer

Completed

Push — master ( 368282...c4d7dc )

by Gytis

created 2019-05-25 08:32 UTC

FqcnMethodSniff::configure() A

↳ Parent: FqcnMethodSniff

Complexity

Conditions	2
Paths	2

Size

Total Lines	11
Code Lines	6

Duplication

Lines	0
Ratio	0 %

Code Coverage

Tests	0
CRAP Score	6

Importance

Changes

Metric	Value
cc	2
eloc	6
nc	2
nop	1
dl	0
loc	11
ccs	0
cts	9
cp	0
crap	6
rs	10
c	0
b	0
f	0

<?php

namespace Gskema\TypeSniff\Sniffs\CodeElement;

use PHP_CodeSniffer\Files\File;
use Gskema\TypeSniff\Core\CodeElement\Element\AbstractFqcnMethodElement;
use Gskema\TypeSniff\Core\CodeElement\Element\ClassMethodElement;
use Gskema\TypeSniff\Core\CodeElement\Element\CodeElementInterface;
use Gskema\TypeSniff\Core\CodeElement\Element\InterfaceMethodElement;
use Gskema\TypeSniff\Core\DocBlock\DocBlock;
use Gskema\TypeSniff\Core\DocBlock\UndefinedDocBlock;
use Gskema\TypeSniff\Core\Type\Common\ArrayType;
use Gskema\TypeSniff\Core\Type\Common\UndefinedType;
use Gskema\TypeSniff\Core\Type\Common\VoidType;
use Gskema\TypeSniff\Core\Type\Declaration\NullableType;
use Gskema\TypeSniff\Core\Type\DocBlock\CompoundType;
use Gskema\TypeSniff\Core\Type\DocBlock\NullType;
use Gskema\TypeSniff\Core\Type\DocBlock\TypedArrayType;
use Gskema\TypeSniff\Core\Type\TypeConverter;
use Gskema\TypeSniff\Core\Type\TypeInterface;

class FqcnMethodSniff implements CodeElementSniffInterface
{
    /** @var string[] */
    protected $baseUsefulTags = [
        '@deprecated',
        '@throws',
        '@dataProvider',
        '@see',
        '@todo',
        '@inheritDoc'
    ];

    /** @var string[] */
    protected $usefulTags = [];

    /**
     * @inheritDoc
     */
    public function configure(array $config): void
    {
        $rawTags = array_merge($this->baseUsefulTags, $config['usefulTags'] ?? []);

        $usefulTags = [];
        foreach ($rawTags as $rawTag) {
            $usefulTags[] = strtolower(ltrim($rawTag, '@'));
        }
        $usefulTags = array_unique($usefulTags);

        $this->usefulTags = $usefulTags;
    }

    /**
     * @inheritDoc
     */
    public function register(): array
    {
        return [
            ClassMethodElement::class,
            // TraitMethodElement::class, // can be used to implement interface, not possible to know if it is extended
            InterfaceMethodElement::class,
        ];
    }

    /**
     * @inheritDoc
     * @param AbstractFqcnMethodElement $method
     */
    public function process(File $file, CodeElementInterface $method): void
    {
        $warningCountBefore = $file->getWarningCount();

        // @TODO Assert description
        $this->processMethod($file, $method);

        $hasNewWarnings = $file->getWarningCount() > $warningCountBefore;
        if (!$hasNewWarnings && $this->hasUselessDocBlock($method)) {
            $file->addWarningOnLine('Useless PHPDoc', $method->getLine(), 'FqcnMethodSniff');
        }
    }

    protected function processMethod(File $file, AbstractFqcnMethodElement $method): void
    {
        $fnSig = $method->getSignature();
        $docBlock = $method->getDocBlock();
        $isMagicMethod = '__' === substr($fnSig->getName(), 0, 2);
        $isConstructMethod = '__construct' === $fnSig->getName();
        $hasInheritDocTag = $docBlock->hasTag('inheritdoc');

        // @inheritDoc
        // __construct can be detected as extended and magic, but we want to inspect it anyway
        if (!$isConstructMethod) {
            if ($hasInheritDocTag || $isMagicMethod) {
                return;
            } elseif ($method->isExtended()) {
                $file->addWarningOnLine('Missing @inheritDoc tag', $method->getLine(), 'FqcnMethodSniff');
                return;
            }
        }

        // @param
        foreach ($fnSig->getParams() as $fnParam) {
            $paramName = $fnParam->getName();
            $tag = $docBlock->getParamTag($paramName);

            $subject = sprintf('parameter $%s', $paramName);

            $fnType = $fnParam->getType();
            $fnTypeLine = $fnParam->getLine();
            $docType = $tag ? $tag->getType() : null;
            $docTypeLine = $tag ? $tag->getLine() : $fnTypeLine;

            $this->processSigType($file, $docBlock, $subject, $fnType, $fnTypeLine, $docType, $docTypeLine);
        }

        // @return
        if (!$isConstructMethod) {
            $docType = $docBlock->getReturnTag();
            $this->processSigType(
                $file,
                $docBlock,
                'return value',
                $fnSig->getReturnType(),
                $fnSig->getReturnLine(),
                $docType ? $docType->getType() : null,
                $docType ? $docType->getLine() : $fnSig->getLine()
            );
        }
    }

    protected function processSigType(
        File $file,
        DocBlock $docBlock,
        string $subject,
        TypeInterface $fnType,
        int $fnTypeLine,
        ?TypeInterface $docType,
        int $docTypeLine
    ): void {
        // @TODO Required mixed[][] instead of array[]

        $warnings = [];
        if ($docBlock instanceof UndefinedDocBlock) {
            // doc_block:undefined, fn_type:?
            if ($fnType instanceof UndefinedType) {
                $warnings[$fnTypeLine] = 'Add type declaration for :subject: or create PHPDoc with type hint';
            } elseif ($this->containsType($fnType, ArrayType::class)) {
                $warnings[$fnTypeLine] = 'Create PHPDoc with typed array type hint for :subject:, .e.g.: "string[]" or "SomeClass[]"';
            }
        } elseif (null === $docType) {
            // doc_block:defined, doc_tag:missing
            if ('return value' === $subject) { // @TODO ??
                if (!($fnType instanceof VoidType)) {
                    $warnings[$fnTypeLine] = 'Missing PHPDoc tag or void type declaration for :subject:';
                }
            } else {
                $warnings[$fnTypeLine] = 'Missing PHPDoc tag for :subject:';
            }
        } elseif ($docType instanceof UndefinedType) {
            // doc_block:defined, doc_type:undefined
            $suggestedFnType = TypeConverter::toExpectedDocType($fnType);
            if (null !== $suggestedFnType) {
                $warnings[$docTypeLine] = sprintf(
                    'Add type hint in PHPDoc tag for :subject:, e.g. "%s"',
                    $suggestedFnType->toString()
                );
            } else {
                $warnings[$docTypeLine] = 'Add type hint in PHPDoc tag for :subject:';
            }
        } elseif ($fnType instanceof UndefinedType) {
            // doc_block:defined, doc_type:defined, fn_type:undefined
            if ($docType instanceof NullType) {
                $warnings[$fnTypeLine] = sprintf('Add type declaration for :subject:');
            } elseif ($suggestedFnType = TypeConverter::toFunctionType($docType)) {
                $warnings[$fnTypeLine] = sprintf('Add type declaration for :subject:, e.g.: "%s"', $suggestedFnType->toString());
            }
        } elseif ($this->containsType($fnType, ArrayType::class)) {
            // doc_block:defined, doc_type:defined, fn_type:array
            $docHasTypedArray = $this->containsType($docType, TypedArrayType::class);
            $docHasArray = $this->containsType($docType, ArrayType::class);

            if ($docHasTypedArray && $docHasArray) {
                $warnings[$docTypeLine] = 'Remove array type, typed array type is present in PHPDoc for :subject:.';
            } elseif (!$docHasTypedArray && $docHasArray) {
                $warnings[$docTypeLine] = 'Replace array type with typed array type in PHPDoc for :subject:. Use mixed[] for generic arrays.';
            } elseif (!$docHasTypedArray && !$docHasArray) {
                $warnings[$docTypeLine] = 'Add typed array type in PHPDoc for :subject:. Use mixed[] for generic arrays.';
            }
        } elseif ($fnType instanceof NullableType) {
            // doc_block:defined, doc_type:defined, fn_type:nullable
            if (!$this->containsType($docType, NullType::class)) {
                $warnings[$docTypeLine] = 'Add "null" type hint in PHPDoc for :subject:';
            }
        } else {
            // doc_block:defined, doc_type:defined, fn_type:defined
            $expectedDocType = TypeConverter::toExpectedDocType($fnType);
            $expectedDocTypes = $expectedDocType instanceof CompoundType
                ? $expectedDocType->getTypes()
                : array_filter([$expectedDocType]);

            foreach ($expectedDocTypes as $expectedDocType) {
                if (!$this->containsType($docType, get_class($expectedDocType))) {
                    $warnings[$docTypeLine] = sprintf('Add "%s" type hint in PHPDoc for :subject:', $fnType->toString());
                }
            }
        }

        foreach ($warnings as $line => $warningTpl) {
            $warning = str_replace(':subject:', $subject, $warningTpl);
            $file->addWarningOnLine($warning, $line, 'FqcnMethodSniff');
        }
    }

    protected function containsType(TypeInterface $type, string $typeClassName): bool
    {
        return is_a($type, $typeClassName)
            || ($type instanceof CompoundType && $type->containsType($typeClassName))
            || ($type instanceof NullableType && $type->containsType($typeClassName));
    }

    protected function hasUselessDocBlock(AbstractFqcnMethodElement $method): bool
    {
        $fnSig = $method->getSignature();
        $docBlock = $method->getDocBlock();

        $usefulTagNames = ['deprecated', 'throws', 'dataprovider', 'see', 'todo', 'inheritdoc']; // @TODO ??
        $usefulTagNames = array_diff($usefulTagNames, ['param', 'return']);

        $docReturnTag = $docBlock->getReturnTag();

        $hasUsefulDescription = $docBlock->hasDescription()
            && !preg_match('#^\w+\s+constructor\.?$#', $docBlock->getDescription());

        if ($docBlock instanceof UndefinedDocBlock
            || $hasUsefulDescription
            || $docBlock->hasOneOfTags($usefulTagNames)
            || ($docReturnTag && $docReturnTag->hasDescription())
        ) {
            return false;
        }

        $paramTags = $docBlock->getParamTags();
        foreach ($paramTags as $paramTag) {
            if ($paramTag->hasDescription()) {
                return false;
            }
        }

        foreach ($fnSig->getParams() as $fnParam) {
            $paramTag = $docBlock->getParamTag($fnParam->getName());
            if (null === $paramTag) {
                continue;
            }

            if ($paramTag->hasDescription()) {
                return false;
            }

            // @TODO Cleaner way?
            $fnType = $fnParam->getType();
            $rawFnType = $fnType instanceof NullableType
                ? $fnType->toDocString()
                : $fnType->toString();
            if ($paramTag->getType()->toString() !== $rawFnType) {
                return false;
            }
        }

        $returnTag  = $docBlock->getReturnTag();
        $returnType = $fnSig->getReturnType();

        // @TODO ??
        if ($returnTag && $returnType) {
            $rawReturnType = $returnType instanceof NullableType
                ? $returnType->toDocString()
                : $returnType->toString();
            if ($returnTag->getType()->toString() !== $rawReturnType) {
                return false;
            }
        }

        return true;
    }
}


1			<?php
2
3			namespace Gskema\TypeSniff\Sniffs\CodeElement;
4
5			use PHP_CodeSniffer\Files\File;
6			use Gskema\TypeSniff\Core\CodeElement\Element\AbstractFqcnMethodElement;
7			use Gskema\TypeSniff\Core\CodeElement\Element\ClassMethodElement;
8			use Gskema\TypeSniff\Core\CodeElement\Element\CodeElementInterface;
9			use Gskema\TypeSniff\Core\CodeElement\Element\InterfaceMethodElement;
10			use Gskema\TypeSniff\Core\DocBlock\DocBlock;
11			use Gskema\TypeSniff\Core\DocBlock\UndefinedDocBlock;
12			use Gskema\TypeSniff\Core\Type\Common\ArrayType;
13			use Gskema\TypeSniff\Core\Type\Common\UndefinedType;
14			use Gskema\TypeSniff\Core\Type\Common\VoidType;
15			use Gskema\TypeSniff\Core\Type\Declaration\NullableType;
16			use Gskema\TypeSniff\Core\Type\DocBlock\CompoundType;
17			use Gskema\TypeSniff\Core\Type\DocBlock\NullType;
18			use Gskema\TypeSniff\Core\Type\DocBlock\TypedArrayType;
19			use Gskema\TypeSniff\Core\Type\TypeConverter;
20			use Gskema\TypeSniff\Core\Type\TypeInterface;
21
22			class FqcnMethodSniff implements CodeElementSniffInterface
23			{
24			/** @var string[] */
25			protected $baseUsefulTags = [
26			'@deprecated',
27			'@throws',
28			'@dataProvider',
29			'@see',
30			'@todo',
31			'@inheritDoc'
32			];
33
34			/** @var string[] */
35			protected $usefulTags = [];
36
37			/**
38			* @inheritDoc
39			*/
40			public function configure(array $config): void
41			{
42			$rawTags = array_merge($this->baseUsefulTags, $config['usefulTags'] ?? []);
43
44			$usefulTags = [];
45			foreach ($rawTags as $rawTag) {
46			$usefulTags[] = strtolower(ltrim($rawTag, '@'));
47			}
48			$usefulTags = array_unique($usefulTags);
49
50			$this->usefulTags = $usefulTags;
51			}
52
53			/**
54			* @inheritDoc
55			*/
56			public function register(): array
57			{
58			return [
59			ClassMethodElement::class,
60			// TraitMethodElement::class, // can be used to implement interface, not possible to know if it is extended
61			InterfaceMethodElement::class,
62			];
63			}
64
65			/**
66			* @inheritDoc
67			* @param AbstractFqcnMethodElement $method
68			*/
69			public function process(File $file, CodeElementInterface $method): void
70			{
71			$warningCountBefore = $file->getWarningCount();
72
73			// @TODO Assert description
74			$this->processMethod($file, $method);
75
76			$hasNewWarnings = $file->getWarningCount() > $warningCountBefore;
77			if (!$hasNewWarnings && $this->hasUselessDocBlock($method)) {
78			$file->addWarningOnLine('Useless PHPDoc', $method->getLine(), 'FqcnMethodSniff');
79			}
80			}
81
82			protected function processMethod(File $file, AbstractFqcnMethodElement $method): void
83			{
84			$fnSig = $method->getSignature();
85			$docBlock = $method->getDocBlock();
86			$isMagicMethod = '__' === substr($fnSig->getName(), 0, 2);
87			$isConstructMethod = '__construct' === $fnSig->getName();
88			$hasInheritDocTag = $docBlock->hasTag('inheritdoc');
89
90			// @inheritDoc
91			// __construct can be detected as extended and magic, but we want to inspect it anyway
92			if (!$isConstructMethod) {
93			if ($hasInheritDocTag \|\| $isMagicMethod) {
94			return;
95			} elseif ($method->isExtended()) {
96			$file->addWarningOnLine('Missing @inheritDoc tag', $method->getLine(), 'FqcnMethodSniff');
97			return;
98			}
99			}
100
101			// @param
102			foreach ($fnSig->getParams() as $fnParam) {
103			$paramName = $fnParam->getName();
104			$tag = $docBlock->getParamTag($paramName);
105
106			$subject = sprintf('parameter $%s', $paramName);
107
108			$fnType = $fnParam->getType();
109			$fnTypeLine = $fnParam->getLine();
110			$docType = $tag ? $tag->getType() : null;
111			$docTypeLine = $tag ? $tag->getLine() : $fnTypeLine;
112
113			$this->processSigType($file, $docBlock, $subject, $fnType, $fnTypeLine, $docType, $docTypeLine);
114			}
115
116			// @return
117			if (!$isConstructMethod) {
118			$docType = $docBlock->getReturnTag();
119			$this->processSigType(
120			$file,
121			$docBlock,
122			'return value',
123			$fnSig->getReturnType(),
124			$fnSig->getReturnLine(),
125			$docType ? $docType->getType() : null,
126			$docType ? $docType->getLine() : $fnSig->getLine()
127			);
128			}
129			}
130
131			protected function processSigType(
132			File $file,
133			DocBlock $docBlock,
134			string $subject,
135			TypeInterface $fnType,
136			int $fnTypeLine,
137			?TypeInterface $docType,
138			int $docTypeLine
139			): void {
140			// @TODO Required mixed[][] instead of array[]
141
142			$warnings = [];
143			if ($docBlock instanceof UndefinedDocBlock) {
144			// doc_block:undefined, fn_type:?
145			if ($fnType instanceof UndefinedType) {
146			$warnings[$fnTypeLine] = 'Add type declaration for :subject: or create PHPDoc with type hint';
147			} elseif ($this->containsType($fnType, ArrayType::class)) {
148			$warnings[$fnTypeLine] = 'Create PHPDoc with typed array type hint for :subject:, .e.g.: "string[]" or "SomeClass[]"';
149			}
150			} elseif (null === $docType) {
151			// doc_block:defined, doc_tag:missing
152			if ('return value' === $subject) { // @TODO ??
153			if (!($fnType instanceof VoidType)) {
154			$warnings[$fnTypeLine] = 'Missing PHPDoc tag or void type declaration for :subject:';
155			}
156			} else {
157			$warnings[$fnTypeLine] = 'Missing PHPDoc tag for :subject:';
158			}
159			} elseif ($docType instanceof UndefinedType) {
160			// doc_block:defined, doc_type:undefined
161			$suggestedFnType = TypeConverter::toExpectedDocType($fnType);
162			if (null !== $suggestedFnType) {
163			$warnings[$docTypeLine] = sprintf(
164			'Add type hint in PHPDoc tag for :subject:, e.g. "%s"',
165			$suggestedFnType->toString()
166			);
167			} else {
168			$warnings[$docTypeLine] = 'Add type hint in PHPDoc tag for :subject:';
169			}
170			} elseif ($fnType instanceof UndefinedType) {
171			// doc_block:defined, doc_type:defined, fn_type:undefined
172			if ($docType instanceof NullType) {
173			$warnings[$fnTypeLine] = sprintf('Add type declaration for :subject:');
174			} elseif ($suggestedFnType = TypeConverter::toFunctionType($docType)) {
175			$warnings[$fnTypeLine] = sprintf('Add type declaration for :subject:, e.g.: "%s"', $suggestedFnType->toString());
176			}
177			} elseif ($this->containsType($fnType, ArrayType::class)) {
178			// doc_block:defined, doc_type:defined, fn_type:array
179			$docHasTypedArray = $this->containsType($docType, TypedArrayType::class);
180			$docHasArray = $this->containsType($docType, ArrayType::class);
181
182			if ($docHasTypedArray && $docHasArray) {
183			$warnings[$docTypeLine] = 'Remove array type, typed array type is present in PHPDoc for :subject:.';
184			} elseif (!$docHasTypedArray && $docHasArray) {
185			$warnings[$docTypeLine] = 'Replace array type with typed array type in PHPDoc for :subject:. Use mixed[] for generic arrays.';
186			} elseif (!$docHasTypedArray && !$docHasArray) {
187			$warnings[$docTypeLine] = 'Add typed array type in PHPDoc for :subject:. Use mixed[] for generic arrays.';
188			}
189			} elseif ($fnType instanceof NullableType) {
190			// doc_block:defined, doc_type:defined, fn_type:nullable
191			if (!$this->containsType($docType, NullType::class)) {
192			$warnings[$docTypeLine] = 'Add "null" type hint in PHPDoc for :subject:';
193			}
194			} else {
195			// doc_block:defined, doc_type:defined, fn_type:defined
196			$expectedDocType = TypeConverter::toExpectedDocType($fnType);
197			$expectedDocTypes = $expectedDocType instanceof CompoundType
198			? $expectedDocType->getTypes()
199			: array_filter([$expectedDocType]);
200
201			foreach ($expectedDocTypes as $expectedDocType) {
202			if (!$this->containsType($docType, get_class($expectedDocType))) {
203			$warnings[$docTypeLine] = sprintf('Add "%s" type hint in PHPDoc for :subject:', $fnType->toString());
204			}
205			}
206			}
207
208			foreach ($warnings as $line => $warningTpl) {
209			$warning = str_replace(':subject:', $subject, $warningTpl);
210			$file->addWarningOnLine($warning, $line, 'FqcnMethodSniff');
211			}
212			}
213
214			protected function containsType(TypeInterface $type, string $typeClassName): bool
215			{
216			return is_a($type, $typeClassName)
217			\|\| ($type instanceof CompoundType && $type->containsType($typeClassName))
218			\|\| ($type instanceof NullableType && $type->containsType($typeClassName));
219			}
220
221			protected function hasUselessDocBlock(AbstractFqcnMethodElement $method): bool
222			{
223			$fnSig = $method->getSignature();
224			$docBlock = $method->getDocBlock();
225
226			$usefulTagNames = ['deprecated', 'throws', 'dataprovider', 'see', 'todo', 'inheritdoc']; // @TODO ??
227			$usefulTagNames = array_diff($usefulTagNames, ['param', 'return']);
228
229			$docReturnTag = $docBlock->getReturnTag();
230
231			$hasUsefulDescription = $docBlock->hasDescription()
232			&& !preg_match('#^\w+\s+constructor\.?$#', $docBlock->getDescription());
233
234			if ($docBlock instanceof UndefinedDocBlock
235			\|\| $hasUsefulDescription
236			\|\| $docBlock->hasOneOfTags($usefulTagNames)
237			\|\| ($docReturnTag && $docReturnTag->hasDescription())
238			) {
239			return false;
240			}
241
242			$paramTags = $docBlock->getParamTags();
243			foreach ($paramTags as $paramTag) {
244			if ($paramTag->hasDescription()) {
245			return false;
246			}
247			}
248
249			foreach ($fnSig->getParams() as $fnParam) {
250			$paramTag = $docBlock->getParamTag($fnParam->getName());
251			if (null === $paramTag) {
252			continue;
253			}
254
255			if ($paramTag->hasDescription()) {
256			return false;
257			}
258
259			// @TODO Cleaner way?
260			$fnType = $fnParam->getType();
261			$rawFnType = $fnType instanceof NullableType
262			? $fnType->toDocString()
263			: $fnType->toString();
264			if ($paramTag->getType()->toString() !== $rawFnType) {
265			return false;
266			}
267			}
268
269			$returnTag = $docBlock->getReturnTag();
270			$returnType = $fnSig->getReturnType();
271
272			// @TODO ??
273			if ($returnTag && $returnType) {
274			$rawReturnType = $returnType instanceof NullableType
275			? $returnType->toDocString()
276			: $returnType->toString();
277			if ($returnTag->getType()->toString() !== $rawReturnType) {
278			return false;
279			}
280			}
281
282			return true;
283			}
284			}
285

gskema / phpcs-type-sniff

Push — master ( 368282...c4d7dc )

FqcnMethodSniff::configure() A

Complexity

Size

Duplication

Code Coverage

Importance

Duplication Side-by-Side

Filter issues like