PhpDocParser: add config for lines in its AST & enable ignoring errors within phpdocs

conf/bleedingEdge.neon

@@ -16,6 +16,8 @@ parameters:
 		checkUnresolvableParameterTypes: true
 		readOnlyByPhpDoc: true
 		phpDocParserRequireWhitespaceBeforeDescription: true
+		phpDocParserIncludeLines: true
+		enableIgnoreErrorsWithinPhpDocs: true
 		runtimeReflectionRules: true
 		notAnalysedTrait: true
 		curlSetOptTypes: true

conf/config.neon

@@ -51,6 +51,8 @@ parameters:
 		checkUnresolvableParameterTypes: false
 		readOnlyByPhpDoc: false
 		phpDocParserRequireWhitespaceBeforeDescription: false
+		phpDocParserIncludeLines: false
+		enableIgnoreErrorsWithinPhpDocs: false
 		runtimeReflectionRules: false
 		notAnalysedTrait: false
 		curlSetOptTypes: false
@@ -389,6 +391,8 @@ services:
 		arguments:
 			requireWhitespaceBeforeDescription: %featureToggles.phpDocParserRequireWhitespaceBeforeDescription%
 			preserveTypeAliasesWithInvalidTypes: true
+			usedAttributes:
+				lines: %featureToggles.phpDocParserIncludeLines%
 
 	-
 		class: PHPStan\PhpDoc\ConstExprParserFactory
@@ -1824,6 +1828,7 @@ services:
 		arguments:
 			parser: @currentPhpVersionPhpParser
 			lexer: @currentPhpVersionLexer
+			enableIgnoreErrorsWithinPhpDocs: %featureToggles.enableIgnoreErrorsWithinPhpDocs%
 		autowired: no
 
 	currentPhpVersionSimpleParser:

conf/parametersSchema.neon

@@ -46,6 +46,8 @@ parametersSchema:
 		checkUnresolvableParameterTypes: bool()
 		readOnlyByPhpDoc: bool()
 		phpDocParserRequireWhitespaceBeforeDescription: bool()
+		phpDocParserIncludeLines: bool()
+		enableIgnoreErrorsWithinPhpDocs: bool()
 		runtimeReflectionRules: bool()
 		notAnalysedTrait: bool()
 		curlSetOptTypes: bool()

src/Parser/RichParser.php

@@ -12,7 +12,8 @@
 use PHPStan\ShouldNotHappenException;
 use function array_filter;
 use function is_string;
-use function str_contains;
+use function strpos;
+use function substr;
 use function substr_count;
 use const ARRAY_FILTER_USE_KEY;
 use const T_COMMENT;
@@ -28,6 +29,7 @@ public function __construct(
 		private Lexer $lexer,
 		private NameResolver $nameResolver,
 		private Container $container,
+		private bool $enableIgnoreErrorsWithinPhpDocs,
 	)
 	{
 	}
@@ -103,14 +105,48 @@ private function getLinesToIgnore(array $tokens): array
 
 			$text = $token[1];
 			$line = $token[2];
-			if (str_contains($text, '@phpstan-ignore-next-line')) {
-				$line++;
-			} elseif (!str_contains($text, '@phpstan-ignore-line')) {
-				continue;
+
+			if ($this->enableIgnoreErrorsWithinPhpDocs) {
+				$lines = $lines +
+					$this->getLinesToIgnoreForTokenByIgnoreComment($text, $line, '@phpstan-ignore-next-line', true) +
+					$this->getLinesToIgnoreForTokenByIgnoreComment($text, $line, '@phpstan-ignore-line');
+
+			} else {
+				if (strpos($text, '@phpstan-ignore-next-line') !== false) {
+					$line++;
+				} elseif (strpos($text, '@phpstan-ignore-line') === false) {
+					continue;
+				}
+
+				$line += substr_count($token[1], "\n");
+				$lines[$line] = null;
 			}
+		}
+
+		return $lines;
+	}
 
-			$line += substr_count($token[1], "\n");
+	/**
+	 * @return array<int, null>
+	 */
+	private function getLinesToIgnoreForTokenByIgnoreComment(
+		string $tokenText,
+		int $tokenLine,
+		string $ignoreComment,
+		bool $ignoreNextLine = false,
+	): array
+	{
+		$lines = [];
+		$positionsOfIgnoreComment = [];
+		$offset = 0;
+
+		while (($pos = strpos($tokenText, $ignoreComment, $offset)) !== false) {
+			$positionsOfIgnoreComment[] = $pos;
+			$offset = $pos + 1;
+		}
 
+		foreach ($positionsOfIgnoreComment as $pos) {
+			$line = $tokenLine + substr_count(substr($tokenText, 0, $pos), "\n") + ($ignoreNextLine ? 1 : 0);
 			$lines[$line] = null;
 		}
 

src/Rules/PhpDoc/InvalidPHPStanDocTagRule.php

@@ -114,7 +114,9 @@ public function processNode(Node $node, Scope $scope): array
 			$errors[] = RuleErrorBuilder::message(sprintf(
 				'Unknown PHPDoc tag: %s',
 				$phpDocTag->name,
-			))->build();
+			))
+				->line(PhpDocLineHelper::detectLine($node, $phpDocTag))
+				->build();
 		}
 
 		return $errors;

src/Rules/PhpDoc/InvalidPhpDocTagValueRule.php

@@ -90,7 +90,9 @@ public function processNode(Node $node, Scope $scope): array
 					$phpDocTag->name,
 					$phpDocTag->value->alias,
 					$this->trimExceptionMessage($phpDocTag->value->type->getException()->getMessage()),
-				))->build();
+				))
+					->line(PhpDocLineHelper::detectLine($node, $phpDocTag))
+					->build();
 
 				continue;
 			} elseif (!($phpDocTag->value instanceof InvalidTagValueNode)) {
@@ -102,7 +104,9 @@ public function processNode(Node $node, Scope $scope): array
 				$phpDocTag->name,
 				$phpDocTag->value->value,
 				$this->trimExceptionMessage($phpDocTag->value->exception->getMessage()),
-			))->build();
+			))
+				->line(PhpDocLineHelper::detectLine($node, $phpDocTag))
+				->build();
 		}
 
 		return $errors;

src/Rules/PhpDoc/PhpDocLineHelper.php

@@ -0,0 +1,28 @@
+<?php declare(strict_types = 1);
+
+namespace PHPStan\Rules\PhpDoc;
+
+use PhpParser\Node as PhpParserNode;
+use PHPStan\PhpDocParser\Ast\Node as PhpDocNode;
+
+class PhpDocLineHelper
+{
+
+	/**
+	 * This method returns exact line of e.g. `@param` tag in PHPDoc so that it can be used for precise error reporting
+	 * - exact position is available only when bleedingEdge is enabled
+	 * - otherwise, it falls back to given node start line
+	 */
+	public static function detectLine(PhpParserNode $node, PhpDocNode $phpDocNode): int
+	{
+		$phpDocTagLine = $phpDocNode->getAttribute('startLine');
+		$phpDoc = $node->getDocComment();
+
+		if ($phpDocTagLine === null || $phpDoc === null) {
+			return $node->getLine();
+		}
+
+		return $phpDoc->getStartLine() + $phpDocTagLine - 1;
+	}
+
+}

tests/PHPStan/Analyser/AnalyserTest.php

@@ -474,7 +474,7 @@ public function testIgnoreNextLine(bool $reportUnmatchedIgnoredErrors): void
 			__DIR__ . '/data/ignore-next-line.php',
 		], true);
 		$this->assertCount($reportUnmatchedIgnoredErrors ? 4 : 3, $result);
-		foreach ([10, 30, 34] as $i => $line) {
+		foreach ([10, 20, 24] as $i => $line) {
 			$this->assertArrayHasKey($i, $result);
 			$this->assertInstanceOf(Error::class, $result[$i]);
 			$this->assertSame('Fail.', $result[$i]->getMessage());
@@ -487,8 +487,20 @@ public function testIgnoreNextLine(bool $reportUnmatchedIgnoredErrors): void
 
 		$this->assertArrayHasKey(3, $result);
 		$this->assertInstanceOf(Error::class, $result[3]);
-		$this->assertSame('No error to ignore is reported on line 38.', $result[3]->getMessage());
-		$this->assertSame(38, $result[3]->getLine());
+		$this->assertSame('No error to ignore is reported on line 28.', $result[3]->getMessage());
+		$this->assertSame(28, $result[3]->getLine());
+	}
+
+	public function testIgnoreNextLineLegacyBehaviour(): void
+	{
+		$result = $this->runAnalyser([], false, [__DIR__ . '/data/ignore-next-line-legacy.php'], true, false);
+
+		foreach ([10, 32, 36] as $i => $line) {
+			$this->assertArrayHasKey($i, $result);
+			$this->assertInstanceOf(Error::class, $result[$i]);
+			$this->assertSame('Fail.', $result[$i]->getMessage());
+			$this->assertSame($line, $result[$i]->getLine());
+		}
 	}
 
 	/**
@@ -577,9 +589,10 @@ private function runAnalyser(
 		bool $reportUnmatchedIgnoredErrors,
 		$filePaths,
 		bool $onlyFiles,
+		bool $enableIgnoreErrorsWithinPhpDocs = true,
 	): array
 	{
-		$analyser = $this->createAnalyser($reportUnmatchedIgnoredErrors);
+		$analyser = $this->createAnalyser($reportUnmatchedIgnoredErrors, $enableIgnoreErrorsWithinPhpDocs);
 
 		if (is_string($filePaths)) {
 			$filePaths = [$filePaths];
@@ -610,7 +623,7 @@ private function runAnalyser(
 		);
 	}
 
-	private function createAnalyser(bool $reportUnmatchedIgnoredErrors): Analyser
+	private function createAnalyser(bool $reportUnmatchedIgnoredErrors, bool $enableIgnoreErrorsWithinPhpDocs): Analyser
 	{
 		$ruleRegistry = new DirectRuleRegistry([
 			new AlwaysFailRule(),
@@ -658,6 +671,7 @@ private function createAnalyser(bool $reportUnmatchedIgnoredErrors): Analyser
 				$lexer,
 				new NameResolver(),
 				self::getContainer(),
+				$enableIgnoreErrorsWithinPhpDocs,
 			),
 			new DependencyResolver($fileHelper, $reflectionProvider, new ExportedNodeResolver($fileTypeMapper, new ExprPrinter(new Printer())), $fileTypeMapper),
 			new RuleErrorTransformer(),

tests/PHPStan/Analyser/data/ignore-next-line-legacy.php

@@ -0,0 +1,40 @@
+<?php
+
+namespace IgnoreNextLineLegacy;
+
+class Foo
+{
+
+	public function doFoo(): void
+	{
+		fail(); // reported
+
+		// @phpstan-ignore-next-line
+		fail();
+
+		/* @phpstan-ignore-next-line */
+		fail();
+
+		/** @phpstan-ignore-next-line */
+		fail();
+
+		/*
+		 * @phpstan-ignore-next-line
+		 */
+		fail();
+
+		/**
+		 * @phpstan-ignore-next-line
+		 *
+		 * This is the legacy behaviour, the next line is meant as next-non-comment-line
+		 */
+		fail();
+		fail(); // reported
+
+		// @phpstan-ignore-next-line
+		if (fail()) {
+			fail(); // reported
+		}
+	}
+
+}

tests/PHPStan/Analyser/data/ignore-next-line.php

@@ -17,16 +17,6 @@ public function doFoo(): void
 
 		/** @phpstan-ignore-next-line */
 		fail();
-
-		/*
-		 * @phpstan-ignore-next-line
-		 */
-		fail();
-
-		/**
-		 * @phpstan-ignore-next-line
-		 */
-		fail();
 		fail(); // reported
 
 		// @phpstan-ignore-next-line

tests/PHPStan/Rules/PhpDoc/InvalidPHPStanDocTagRuleTest.php

@@ -30,26 +30,26 @@ public function dataRule(): iterable
 		$errors = [
 			[
 				'Unknown PHPDoc tag: @phpstan-extens',
-				7,
+				6,
 			],
 			[
 				'Unknown PHPDoc tag: @phpstan-pararm',
-				14,
+				11,
 			],
 			[
 				'Unknown PHPDoc tag: @phpstan-varr',
-				44,
+				43,
 			],
 			[
 				'Unknown PHPDoc tag: @phpstan-varr',
-				47,
+				46,
 			],
 		];
 		yield [false, $errors];
 		yield [true, array_merge($errors, [
 			[
 				'Unknown PHPDoc tag: @phpstan-varr',
-				57,
+				56,
 			],
 		])];
 	}