FqcnMethodSniff::processMethod() - Code Metrics - Inspection of "Update inheritdoc tag conditional: remove redundan..." - gskema/phpcs-type-sniff - Measure and Improve Code Quality continuously with Scrutinizer

Passed

Push — master ( d83336...d7c119 )

by Gytis

created 2019-05-05 18:44 UTC

FqcnMethodSniff::processMethod() B

↳ Parent: FqcnMethodSniff

Complexity

Conditions	11
Paths	22

Size

Total Lines	45
Code Lines	30

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
cc	11
eloc	30
nc	22
nop	2
dl	0
loc	45
rs	7.3166
c	0
b	0
f	0

How to fix Complexity

<?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
{
    /**
     * @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();

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

gskema / phpcs-type-sniff

Push — master ( d83336...d7c119 )

FqcnMethodSniff::processMethod() B

Complexity

Size

Duplication

Importance

How to fix Complexity

Long Method

Duplication Side-by-Side

Filter issues like