2018-11-06 03:57:36 +01:00
|
|
|
<?php
|
|
|
|
namespace Psalm;
|
|
|
|
|
2021-06-08 04:55:21 +02:00
|
|
|
use Psalm\Exception\DocblockParseException;
|
|
|
|
use Psalm\Internal\Scanner\ParsedDocblock;
|
|
|
|
|
2019-07-05 22:24:00 +02:00
|
|
|
use function array_filter;
|
2019-06-26 22:52:29 +02:00
|
|
|
use function explode;
|
|
|
|
use function implode;
|
2019-07-05 22:24:00 +02:00
|
|
|
use function in_array;
|
|
|
|
use function min;
|
|
|
|
use function preg_match;
|
2019-06-26 22:52:29 +02:00
|
|
|
use function preg_match_all;
|
2019-07-05 22:24:00 +02:00
|
|
|
use function preg_replace;
|
|
|
|
use function rtrim;
|
2019-06-26 22:52:29 +02:00
|
|
|
use function str_repeat;
|
2019-07-05 22:24:00 +02:00
|
|
|
use function str_replace;
|
|
|
|
use function strlen;
|
2021-06-08 04:55:21 +02:00
|
|
|
use function strspn;
|
2019-07-05 22:24:00 +02:00
|
|
|
use function substr;
|
|
|
|
use function trim;
|
2021-06-08 04:55:21 +02:00
|
|
|
|
|
|
|
use const PREG_SET_ORDER;
|
2018-11-06 03:57:36 +01:00
|
|
|
|
|
|
|
class DocComment
|
|
|
|
{
|
2020-11-28 03:48:16 +01:00
|
|
|
public const PSALM_ANNOTATIONS = [
|
2020-04-03 04:38:10 +02:00
|
|
|
'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',
|
2020-05-22 04:47:58 +02:00
|
|
|
'allow-private-mutation', 'readonly-allow-private-mutation',
|
2020-06-21 17:43:08 +02:00
|
|
|
'yield', 'trace', 'import-type', 'flow', 'taint-specialize', 'taint-escape',
|
2020-10-19 21:08:18 +02:00
|
|
|
'taint-unescape', 'self-out', 'consistent-constructor', 'stub-override',
|
2021-04-10 19:16:14 +02:00
|
|
|
'require-extends', 'require-implements', 'param-out', 'ignore-var',
|
|
|
|
'consistent-templates',
|
2020-04-03 04:38:10 +02:00
|
|
|
];
|
|
|
|
|
2019-06-02 00:44:59 +02:00
|
|
|
/**
|
|
|
|
* 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
|
|
|
|
*
|
|
|
|
* @return array Array of the main comment and specials
|
2020-08-23 19:52:31 +02:00
|
|
|
*
|
2019-06-02 00:44:59 +02:00
|
|
|
* @psalm-return array{description:string, specials:array<string, array<int, string>>}
|
2020-05-29 04:14:41 +02:00
|
|
|
* @psalm-suppress PossiblyUnusedMethod
|
|
|
|
*
|
2021-06-20 20:12:20 +02:00
|
|
|
* @deprecated use parsePreservingLength instead, going to be removed in Psalm 5
|
2020-08-23 19:52:31 +02:00
|
|
|
*
|
|
|
|
* @psalm-pure
|
2019-06-02 00:44:59 +02:00
|
|
|
*/
|
2020-09-07 01:36:47 +02:00
|
|
|
public static function parse(string $docblock, ?int $line_number = null, bool $preserve_format = false): array
|
2018-11-06 03:57:36 +01:00
|
|
|
{
|
|
|
|
// Strip off comments.
|
|
|
|
$docblock = trim($docblock);
|
2019-06-02 07:10:50 +02:00
|
|
|
$docblock = preg_replace('@^/\*\*@', '', $docblock);
|
2018-11-06 03:57:36 +01:00
|
|
|
$docblock = preg_replace('@\*/$@', '', $docblock);
|
2019-06-02 07:10:50 +02:00
|
|
|
$docblock = preg_replace('@^[ \t]*\*@m', '', $docblock);
|
2018-11-06 03:57:36 +01:00
|
|
|
|
|
|
|
// Normalize multi-line @specials.
|
|
|
|
$lines = explode("\n", $docblock);
|
|
|
|
|
2019-06-02 07:10:50 +02:00
|
|
|
$line_map = [];
|
2018-11-06 03:57:36 +01:00
|
|
|
|
|
|
|
$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];
|
2019-06-02 07:10:50 +02:00
|
|
|
$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;
|
|
|
|
}
|
2018-11-06 03:57:36 +01:00
|
|
|
|
|
|
|
unset($lines[$k]);
|
|
|
|
}
|
2019-06-02 07:10:50 +02:00
|
|
|
|
|
|
|
if ($line_number) {
|
|
|
|
$line_map[$line] = $line_number++;
|
|
|
|
}
|
2018-11-06 03:57:36 +01:00
|
|
|
}
|
|
|
|
|
2019-06-02 07:10:50 +02:00
|
|
|
$special = [];
|
2018-11-06 03:57:36 +01:00
|
|
|
|
2019-06-02 07:10:50 +02:00
|
|
|
if ($preserve_format) {
|
|
|
|
foreach ($lines as $m => $line) {
|
|
|
|
if (preg_match('/^\s?@([\w\-:]+)[\t ]*(.*)$/sm', $line, $matches)) {
|
2020-09-02 06:17:41 +02:00
|
|
|
[$full_match, $type, $data] = $matches;
|
2018-11-06 03:57:36 +01:00
|
|
|
|
2019-06-02 07:10:50 +02:00
|
|
|
$docblock = str_replace($full_match, '', $docblock);
|
2018-11-06 03:57:36 +01:00
|
|
|
|
2019-06-02 07:10:50 +02:00
|
|
|
if (empty($special[$type])) {
|
|
|
|
$special[$type] = [];
|
|
|
|
}
|
2018-11-06 03:57:36 +01:00
|
|
|
|
2020-11-25 18:04:48 +01:00
|
|
|
$line_number = $line_map && isset($line_map[$full_match]) ? $line_map[$full_match] : $m;
|
2019-06-02 07:10:50 +02:00
|
|
|
|
|
|
|
$special[$type][$line_number] = rtrim($data);
|
2018-11-06 03:57:36 +01:00
|
|
|
}
|
2019-06-02 07:10:50 +02:00
|
|
|
}
|
|
|
|
} else {
|
|
|
|
$docblock = implode("\n", $lines);
|
2018-11-06 03:57:36 +01:00
|
|
|
|
2019-06-02 07:10:50 +02:00
|
|
|
// 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);
|
|
|
|
foreach ($matches as $m => $match) {
|
2020-09-02 06:17:41 +02:00
|
|
|
[$_, $type, $data] = $match;
|
2018-11-06 03:57:36 +01:00
|
|
|
|
2019-06-02 07:10:50 +02:00
|
|
|
if (empty($special[$type])) {
|
|
|
|
$special[$type] = [];
|
|
|
|
}
|
|
|
|
|
2020-11-25 18:04:48 +01:00
|
|
|
$line_number = $line_map && isset($line_map[$_]) ? $line_map[$_] : $m;
|
2019-06-01 22:57:33 +02:00
|
|
|
|
2019-06-02 07:10:50 +02:00
|
|
|
$special[$type][$line_number] = $data;
|
|
|
|
}
|
|
|
|
}
|
2018-11-06 03:57:36 +01:00
|
|
|
}
|
|
|
|
|
|
|
|
$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) {
|
2020-10-15 19:23:35 +02:00
|
|
|
for ($ii = 0, $iiMax = strlen($line); $ii < $iiMax; ++$ii) {
|
2020-09-20 00:26:51 +02:00
|
|
|
if ($line[$ii] !== ' ') {
|
2018-11-06 03:57:36 +01:00
|
|
|
break;
|
|
|
|
}
|
|
|
|
++$indent;
|
|
|
|
}
|
|
|
|
|
|
|
|
$min_indent = min($indent, $min_indent);
|
|
|
|
}
|
2019-06-02 00:44:59 +02:00
|
|
|
|
|
|
|
$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,
|
2020-04-03 04:38:10 +02:00
|
|
|
self::PSALM_ANNOTATIONS,
|
2019-07-05 22:24:00 +02:00
|
|
|
true
|
2019-06-02 00:44:59 +02:00
|
|
|
)) {
|
|
|
|
throw new DocblockParseException('Unrecognised annotation @psalm-' . $special_key);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
|
|
|
return [
|
|
|
|
'description' => $docblock,
|
|
|
|
'specials' => $special,
|
|
|
|
];
|
|
|
|
}
|
|
|
|
|
|
|
|
/**
|
|
|
|
* Parse a docblock comment into its parts.
|
|
|
|
*/
|
2020-05-29 04:14:41 +02:00
|
|
|
public static function parsePreservingLength(\PhpParser\Comment\Doc $docblock) : ParsedDocblock
|
2019-06-02 00:44:59 +02:00
|
|
|
{
|
2021-08-06 22:00:37 +02:00
|
|
|
$parsed_docblock = \Psalm\Internal\Scanner\DocblockParser::parse(
|
|
|
|
$docblock->getText(),
|
|
|
|
$docblock->getStartFilePos()
|
|
|
|
);
|
2019-06-02 00:44:59 +02:00
|
|
|
|
2020-05-29 04:14:41 +02:00
|
|
|
foreach ($parsed_docblock->tags as $special_key => $_) {
|
2018-12-01 21:29:14 +01:00
|
|
|
if (substr($special_key, 0, 6) === 'psalm-') {
|
|
|
|
$special_key = substr($special_key, 6);
|
|
|
|
|
|
|
|
if (!in_array(
|
|
|
|
$special_key,
|
2020-04-03 04:38:10 +02:00
|
|
|
self::PSALM_ANNOTATIONS,
|
2019-07-05 22:24:00 +02:00
|
|
|
true
|
2018-12-01 21:29:14 +01:00
|
|
|
)) {
|
|
|
|
throw new DocblockParseException('Unrecognised annotation @psalm-' . $special_key);
|
|
|
|
}
|
|
|
|
}
|
|
|
|
}
|
|
|
|
|
2020-05-29 04:14:41 +02:00
|
|
|
return $parsed_docblock;
|
2020-03-13 17:40:08 +01:00
|
|
|
}
|
2020-09-13 22:41:14 +02:00
|
|
|
|
|
|
|
/**
|
|
|
|
* @psalm-pure
|
|
|
|
* @return array<int,string>
|
|
|
|
*/
|
|
|
|
public static function parseSuppressList(string $suppress_entry): array
|
|
|
|
{
|
|
|
|
preg_match(
|
|
|
|
'/
|
|
|
|
(?(DEFINE)
|
|
|
|
# either a single issue or comma separated list of issues
|
|
|
|
(?<issue_list> (?&issue) \s* , \s* (?&issue_list) | (?&issue) )
|
|
|
|
|
|
|
|
# definition of a single issue
|
|
|
|
(?<issue> [A-Za-z0-9_-]+ )
|
|
|
|
)
|
|
|
|
^ (?P<issues> (?&issue_list) ) (?P<description> .* ) $
|
|
|
|
/xm',
|
|
|
|
$suppress_entry,
|
|
|
|
$matches
|
|
|
|
);
|
|
|
|
|
|
|
|
if (!isset($matches['issues'])) {
|
|
|
|
return [];
|
|
|
|
}
|
|
|
|
|
|
|
|
$issue_offset = 0;
|
|
|
|
$ret = [];
|
|
|
|
|
|
|
|
foreach (explode(',', $matches['issues']) as $suppressed_issue) {
|
|
|
|
$issue_offset += strspn($suppressed_issue, "\t\n\f\r ");
|
|
|
|
$ret[$issue_offset] = trim($suppressed_issue);
|
|
|
|
$issue_offset += strlen($suppressed_issue) + 1;
|
|
|
|
}
|
|
|
|
|
|
|
|
return $ret;
|
|
|
|
}
|
2018-11-06 03:57:36 +01:00
|
|
|
}
|