DocComment::parsePreservingLength() - Code Metrics - vimeo/psalm - Measure and Improve Code Quality continuously with Scrutinizer

DocComment::parsePreservingLength() A
last analyzed 2020-07-20 09:18 UTC

↳ Parent: DocComment

Complexity

Conditions	4
Paths	4

Size

Total Lines

Duplication

Lines	0
Ratio	0 %

Importance

Changes

Metric	Value
cc	4
nc	4
nop	1
dl	0
loc	20
rs	9.6
c	0
b	0
f	0

<?php
namespace Psalm;

use function array_filter;
use function explode;
use function implode;
use function in_array;
use function min;
use function preg_match;
use function preg_match_all;
use const PREG_OFFSET_CAPTURE;
use function preg_replace;
use const PREG_SET_ORDER;
use Psalm\Internal\Scanner\ParsedDocblock;
use Psalm\Exception\DocblockParseException;
use function rtrim;
use function str_repeat;
use function str_replace;
use function strlen;
use function strpos;
use function substr;
use function trim;

class DocComment
{
    private const PSALM_ANNOTATIONS = [
        'return', 'param', 'template', 'var', 'type',
        'template-covariant', 'property', 'property-read', 'property-write', 'method',
        'assert', 'assert-if-true', 'assert-if-false', 'suppress',
        'ignore-nullable-return', 'override-property-visibility',
        'override-method-visibility', 'seal-properties', 'seal-methods',
        'generator-return', 'ignore-falsable-return', 'variadic', 'pure',
        'ignore-variable-method', 'ignore-variable-property', 'internal',
        'taint-sink', 'taint-source', 'assert-untainted', 'scope-this',
        'mutation-free', 'external-mutation-free', 'immutable', 'readonly',
        'allow-private-mutation', 'readonly-allow-private-mutation',
        'yield', 'trace', 'import-type', 'flow', 'taint-specialize', 'taint-escape',
        'taint-unescape', 'self-out'
    ];

    /**
     * Parse a docblock comment into its parts.
     *
     * Taken from advanced api docmaker, which was taken from
     * https://github.com/facebook/libphutil/blob/master/src/parser/docblock/PhutilDocblockParser.php
     *
     * @param  string  $docblock
     * @param  int     $line_number
     * @param  bool    $preserve_format
     *
     * @return array Array of the main comment and specials
     * @psalm-return array{description:string, specials:array<string, array<int, string>>}
     * @psalm-suppress PossiblyUnusedMethod
     *
     * @deprecated use parsePreservingLength instead
     */
    public static function parse($docblock, $line_number = null, $preserve_format = false)
    {
        // Strip off comments.
        $docblock = trim($docblock);
        $docblock = preg_replace('@^/\*\*@', '', $docblock);
        $docblock = preg_replace('@\*/$@', '', $docblock);
        $docblock = preg_replace('@^[ \t]*\*@m', '', $docblock);

        // Normalize multi-line @specials.
        $lines = explode("\n", $docblock);

        $line_map = [];

        $last = false;
        foreach ($lines as $k => $line) {
            if (preg_match('/^\s?@\w/i', $line)) {
                $last = $k;
            } elseif (preg_match('/^\s*$/', $line)) {
                $last = false;
            } elseif ($last !== false) {
                $old_last_line = $lines[$last];
                $lines[$last] = rtrim($old_last_line)
                    . ($preserve_format || trim($old_last_line) === '@return' ? "\n" . $line : ' ' . trim($line));

                if ($line_number) {
                    $old_line_number = $line_map[$old_last_line];
                    unset($line_map[$old_last_line]);
                    $line_map[$lines[$last]] = $old_line_number;
                }

                unset($lines[$k]);
            }

            if ($line_number) {
                $line_map[$line] = $line_number++;
            }
        }

        $special = [];

        if ($preserve_format) {
            foreach ($lines as $m => $line) {
                if (preg_match('/^\s?@([\w\-:]+)[\t ]*(.*)$/sm', $line, $matches)) {
                    list($full_match, $type, $data) = $matches;

                    $docblock = str_replace($full_match, '', $docblock);

                    if (empty($special[$type])) {
                        $special[$type] = [];
                    }

                    $line_number = $line_map && isset($line_map[$full_match]) ? $line_map[$full_match] : (int)$m;

                    $special[$type][$line_number] = rtrim($data);
                }
            }
        } else {
            $docblock = implode("\n", $lines);

            // Parse @specials.
            if (preg_match_all('/^\s?@([\w\-:]+)[\t ]*([^\n]*)/m', $docblock, $matches, PREG_SET_ORDER)) {
                $docblock = preg_replace('/^\s?@([\w\-:]+)\s*([^\n]*)/m', '', $docblock);
                /** @var string[] $match */
                foreach ($matches as $m => $match) {
                    list($_, $type, $data) = $match;

                    if (empty($special[$type])) {
                        $special[$type] = [];
                    }

                    $line_number = $line_map && isset($line_map[$_]) ? $line_map[$_] : (int)$m;

                    $special[$type][$line_number] = $data;
                }
            }
        }

        $docblock = str_replace("\t", '  ', $docblock);

        // Smush the whole docblock to the left edge.
        $min_indent = 80;
        $indent = 0;
        foreach (array_filter(explode("\n", $docblock)) as $line) {
            for ($ii = 0; $ii < strlen($line); ++$ii) {
                if ($line[$ii] != ' ') {
                    break;
                }
                ++$indent;
            }

            $min_indent = min($indent, $min_indent);
        }

        $docblock = preg_replace('/^' . str_repeat(' ', $min_indent) . '/m', '', $docblock);
        $docblock = rtrim($docblock);

        // Trim any empty lines off the front, but leave the indent level if there
        // is one.
        $docblock = preg_replace('/^\s*\n/', '', $docblock);

        foreach ($special as $special_key => $_) {
            if (substr($special_key, 0, 6) === 'psalm-') {
                $special_key = substr($special_key, 6);

                if (!in_array(
                    $special_key,
                    self::PSALM_ANNOTATIONS,
                    true
                )) {
                    throw new DocblockParseException('Unrecognised annotation @psalm-' . $special_key);
                }
            }
        }

        return [
            'description' => $docblock,
            'specials' => $special,
        ];
    }

    /**
     * Parse a docblock comment into its parts.
     *
     * @param  \PhpParser\Comment\Doc  $docblock
     * @param  bool    $preserve_format
/**
 * @param array $germany
 * @param array $island
 * @param array $italy
 */
function finale($germany, $island) {
    return "2:1";
}
     */
    public static function parsePreservingLength(\PhpParser\Comment\Doc $docblock) : ParsedDocblock
    {
        $parsed_docblock = \Psalm\Internal\Scanner\DocblockParser::parse($docblock->getText());

        foreach ($parsed_docblock->tags as $special_key => $_) {
            if (substr($special_key, 0, 6) === 'psalm-') {
                $special_key = substr($special_key, 6);

                if (!in_array(
                    $special_key,
                    self::PSALM_ANNOTATIONS,
                    true
                )) {
                    throw new DocblockParseException('Unrecognised annotation @psalm-' . $special_key);
                }
            }
        }

        return $parsed_docblock;
    }
}


1			<?php
2			namespace Psalm;
3
4			use function array_filter;
5			use function explode;
6			use function implode;
7			use function in_array;
8			use function min;
9			use function preg_match;
10			use function preg_match_all;
11			use const PREG_OFFSET_CAPTURE;
12			use function preg_replace;
13			use const PREG_SET_ORDER;
14			use Psalm\Internal\Scanner\ParsedDocblock;
15			use Psalm\Exception\DocblockParseException;
16			use function rtrim;
17			use function str_repeat;
18			use function str_replace;
19			use function strlen;
20			use function strpos;
21			use function substr;
22			use function trim;
23
24			class DocComment
25			{
26			private const PSALM_ANNOTATIONS = [
27			'return', 'param', 'template', 'var', 'type',
28			'template-covariant', 'property', 'property-read', 'property-write', 'method',
29			'assert', 'assert-if-true', 'assert-if-false', 'suppress',
30			'ignore-nullable-return', 'override-property-visibility',
31			'override-method-visibility', 'seal-properties', 'seal-methods',
32			'generator-return', 'ignore-falsable-return', 'variadic', 'pure',
33			'ignore-variable-method', 'ignore-variable-property', 'internal',
34			'taint-sink', 'taint-source', 'assert-untainted', 'scope-this',
35			'mutation-free', 'external-mutation-free', 'immutable', 'readonly',
36			'allow-private-mutation', 'readonly-allow-private-mutation',
37			'yield', 'trace', 'import-type', 'flow', 'taint-specialize', 'taint-escape',
38			'taint-unescape', 'self-out'
39			];
40
41			/**
42			* Parse a docblock comment into its parts.
43			*
44			* Taken from advanced api docmaker, which was taken from
45			* https://github.com/facebook/libphutil/blob/master/src/parser/docblock/PhutilDocblockParser.php
46			*
47			* @param string $docblock
48			* @param int $line_number
49			* @param bool $preserve_format
50			*
51			* @return array Array of the main comment and specials
52			* @psalm-return array{description:string, specials:array<string, array<int, string>>}
53			* @psalm-suppress PossiblyUnusedMethod
54			*
55			* @deprecated use parsePreservingLength instead
56			*/
57			public static function parse($docblock, $line_number = null, $preserve_format = false)
58			{
59			// Strip off comments.
60			$docblock = trim($docblock);
61			$docblock = preg_replace('@^/\\@', '', $docblock);
62			$docblock = preg_replace('@\*/$@', '', $docblock);
63			$docblock = preg_replace('@^[ \t]\@m', '', $docblock);
64
65			// Normalize multi-line @specials.
66			$lines = explode("\n", $docblock);
67
68			$line_map = [];
69
70			$last = false;
71			foreach ($lines as $k => $line) {
72			if (preg_match('/^\s?@\w/i', $line)) {
73			$last = $k;
74			} elseif (preg_match('/^\s*$/', $line)) {
75			$last = false;
76			} elseif ($last !== false) {
77			$old_last_line = $lines[$last];
78			$lines[$last] = rtrim($old_last_line)
79			. ($preserve_format \|\| trim($old_last_line) === '@return' ? "\n" . $line : ' ' . trim($line));
80
81			if ($line_number) {
82			$old_line_number = $line_map[$old_last_line];
83			unset($line_map[$old_last_line]);
84			$line_map[$lines[$last]] = $old_line_number;
85			}
86
87			unset($lines[$k]);
88			}
89
90			if ($line_number) {
91			$line_map[$line] = $line_number++;
92			}
93			}
94
95			$special = [];
96
97			if ($preserve_format) {
98			foreach ($lines as $m => $line) {
99			if (preg_match('/^\s?@([\w\-:]+)[\t ](.)$/sm', $line, $matches)) {
100			list($full_match, $type, $data) = $matches;
101
102			$docblock = str_replace($full_match, '', $docblock);
103
104			if (empty($special[$type])) {
105			$special[$type] = [];
106			}
107
108			$line_number = $line_map && isset($line_map[$full_match]) ? $line_map[$full_match] : (int)$m;
109
110			$special[$type][$line_number] = rtrim($data);
111			}
112			}
113			} else {
114			$docblock = implode("\n", $lines);
115
116			// Parse @specials.
117			if (preg_match_all('/^\s?@([\w\-:]+)[\t ]([^\n])/m', $docblock, $matches, PREG_SET_ORDER)) {
118			$docblock = preg_replace('/^\s?@([\w\-:]+)\s([^\n])/m', '', $docblock);
119			/** @var string[] $match */
120			foreach ($matches as $m => $match) {
121			list($_, $type, $data) = $match;
122
123			if (empty($special[$type])) {
124			$special[$type] = [];
125			}
126
127			$line_number = $line_map && isset($line_map[$_]) ? $line_map[$_] : (int)$m;
128
129			$special[$type][$line_number] = $data;
130			}
131			}
132			}
133
134			$docblock = str_replace("\t", ' ', $docblock);
135
136			// Smush the whole docblock to the left edge.
137			$min_indent = 80;
138			$indent = 0;
139			foreach (array_filter(explode("\n", $docblock)) as $line) {
140			for ($ii = 0; $ii < strlen($line); ++$ii) {
141			if ($line[$ii] != ' ') {
142			break;
143			}
144			++$indent;
145			}
146
147			$min_indent = min($indent, $min_indent);
148			}
149
150			$docblock = preg_replace('/^' . str_repeat(' ', $min_indent) . '/m', '', $docblock);
151			$docblock = rtrim($docblock);
152
153			// Trim any empty lines off the front, but leave the indent level if there
154			// is one.
155			$docblock = preg_replace('/^\s*\n/', '', $docblock);
156
157			foreach ($special as $special_key => $_) {
158			if (substr($special_key, 0, 6) === 'psalm-') {
159			$special_key = substr($special_key, 6);
160
161			if (!in_array(
162			$special_key,
163			self::PSALM_ANNOTATIONS,
164			true
165			)) {
166			throw new DocblockParseException('Unrecognised annotation @psalm-' . $special_key);
167			}
168			}
169			}
170
171			return [
172			'description' => $docblock,
173			'specials' => $special,
174			];
175			}
176
177			/**
178			* Parse a docblock comment into its parts.
179			*
180			* @param \PhpParser\Comment\Doc $docblock
181			* @param bool $preserve_format
			0 ignored issues – show Bug introduced 2020-05-19 22:00 UTC by Report Bug Copy Issue Report There is no parameter named `$preserve_format`. Was it maybe removed? This check looks for PHPDoc comments describing methods or function parameters that do not exist on the corresponding method or function. Consider the following example. The parameter `$italy` is not defined by the method `finale(...)`. /** * @param array $germany * @param array $island * @param array $italy */ function finale($germany, $island) { return "2:1"; } The most likely cause is that the parameter was removed, but the annotation was not. Loading history...
182			*/
183			public static function parsePreservingLength(\PhpParser\Comment\Doc $docblock) : ParsedDocblock
184			{
185			$parsed_docblock = \Psalm\Internal\Scanner\DocblockParser::parse($docblock->getText());
186
187			foreach ($parsed_docblock->tags as $special_key => $_) {
188			if (substr($special_key, 0, 6) === 'psalm-') {
189			$special_key = substr($special_key, 6);
190
191			if (!in_array(
192			$special_key,
193			self::PSALM_ANNOTATIONS,
194			true
195			)) {
196			throw new DocblockParseException('Unrecognised annotation @psalm-' . $special_key);
197			}
198			}
199			}
200
201			return $parsed_docblock;
202			}
203			}
204

vimeo / psalm

DocComment::parsePreservingLength() A last analyzed 2020-07-20 09:18 UTC

Complexity

Size

Duplication

Importance

Duplication Side-by-Side

Filter issues like

DocComment::parsePreservingLength() A
last analyzed 2020-07-20 09:18 UTC