From 09691fc86e9e9bf2b936dcc9d1590a3061d223a7 Mon Sep 17 00:00:00 2001
From: Markus Staab <markus.staab@redaxo.de>
Date: Wed, 13 Mar 2024 11:49:39 +0100
Subject: [PATCH] Prevent off-by-one errors in line-number related methods

---
 lib/PhpParser/Comment.php      | 2 ++
 lib/PhpParser/Error.php        | 2 ++
 lib/PhpParser/Node.php         | 3 +++
 lib/PhpParser/NodeAbstract.php | 3 +++
 4 files changed, 10 insertions(+)

diff --git a/lib/PhpParser/Comment.php b/lib/PhpParser/Comment.php
index 17dc4c73a9..01b341e438 100644
--- a/lib/PhpParser/Comment.php
+++ b/lib/PhpParser/Comment.php
@@ -46,6 +46,7 @@ public function getText(): string {
      * Gets the line number the comment started on.
      *
      * @return int Line number (or -1 if not available)
+     * @phpstan-return -1|positive-int
      */
     public function getStartLine(): int {
         return $this->startLine;
@@ -73,6 +74,7 @@ public function getStartTokenPos(): int {
      * Gets the line number the comment ends on.
      *
      * @return int Line number (or -1 if not available)
+     * @phpstan-return -1|positive-int
      */
     public function getEndLine(): int {
         return $this->endLine;
diff --git a/lib/PhpParser/Error.php b/lib/PhpParser/Error.php
index 02feace0c7..f81f0c4202 100644
--- a/lib/PhpParser/Error.php
+++ b/lib/PhpParser/Error.php
@@ -32,6 +32,7 @@ public function getRawMessage(): string {
      * Gets the line the error starts in.
      *
      * @return int Error start line
+     * @phpstan-return -1|positive-int
      */
     public function getStartLine(): int {
         return $this->attributes['startLine'] ?? -1;
@@ -41,6 +42,7 @@ public function getStartLine(): int {
      * Gets the line the error ends in.
      *
      * @return int Error end line
+     * @phpstan-return -1|positive-int
      */
     public function getEndLine(): int {
         return $this->attributes['endLine'] ?? -1;
diff --git a/lib/PhpParser/Node.php b/lib/PhpParser/Node.php
index 258e45160a..843e2ea66c 100644
--- a/lib/PhpParser/Node.php
+++ b/lib/PhpParser/Node.php
@@ -21,6 +21,7 @@ public function getSubNodeNames(): array;
      * Gets line the node started in (alias of getStartLine).
      *
      * @return int Start line (or -1 if not available)
+     * @phpstan-return -1|positive-int
      *
      * @deprecated Use getStartLine() instead
      */
@@ -32,6 +33,7 @@ public function getLine(): int;
      * Requires the 'startLine' attribute to be enabled in the lexer (enabled by default).
      *
      * @return int Start line (or -1 if not available)
+     * @phpstan-return -1|positive-int
      */
     public function getStartLine(): int;
 
@@ -41,6 +43,7 @@ public function getStartLine(): int;
      * Requires the 'endLine' attribute to be enabled in the lexer (enabled by default).
      *
      * @return int End line (or -1 if not available)
+     * @phpstan-return -1|positive-int
      */
     public function getEndLine(): int;
 
diff --git a/lib/PhpParser/NodeAbstract.php b/lib/PhpParser/NodeAbstract.php
index 7c3a36075c..a6a50aea0f 100644
--- a/lib/PhpParser/NodeAbstract.php
+++ b/lib/PhpParser/NodeAbstract.php
@@ -19,6 +19,7 @@ public function __construct(array $attributes = []) {
      * Gets line the node started in (alias of getStartLine).
      *
      * @return int Start line (or -1 if not available)
+     * @phpstan-return -1|positive-int
      */
     public function getLine(): int {
         return $this->attributes['startLine'] ?? -1;
@@ -30,6 +31,7 @@ public function getLine(): int {
      * Requires the 'startLine' attribute to be enabled in the lexer (enabled by default).
      *
      * @return int Start line (or -1 if not available)
+     * @phpstan-return -1|positive-int
      */
     public function getStartLine(): int {
         return $this->attributes['startLine'] ?? -1;
@@ -41,6 +43,7 @@ public function getStartLine(): int {
      * Requires the 'endLine' attribute to be enabled in the lexer (enabled by default).
      *
      * @return int End line (or -1 if not available)
+     * @phpstan-return -1|positive-int
      */
     public function getEndLine(): int {
         return $this->attributes['endLine'] ?? -1;