From 308d72373747ef20767974e81c164ba390c166fe Mon Sep 17 00:00:00 2001
From: Oliver Klee <github@oliverklee.de>
Date: Sun, 9 Feb 2025 16:19:08 +0100
Subject: [PATCH] [TASK] Use native type declarations for `Renderable`

---
 CHANGELOG.md                             |  2 +-
 src/CSSList/AtRuleBlockList.php          |  2 +-
 src/CSSList/CSSBlockList.php             |  2 +-
 src/CSSList/CSSList.php                  |  8 ++++----
 src/CSSList/Document.php                 |  2 +-
 src/CSSList/KeyFrame.php                 |  2 +-
 src/Comment/Comment.php                  |  8 ++++----
 src/Parser.php                           |  2 +-
 src/Parsing/OutputException.php          |  2 +-
 src/Parsing/ParserState.php              |  2 +-
 src/Parsing/SourceException.php          |  6 +++---
 src/Parsing/UnexpectedTokenException.php |  2 +-
 src/Property/CSSNamespace.php            |  6 +++---
 src/Property/Charset.php                 |  8 ++++----
 src/Property/Import.php                  |  8 ++++----
 src/Renderable.php                       | 14 ++++----------
 src/Rule/Rule.php                        |  6 +++---
 src/RuleSet/AtRuleSet.php                |  2 +-
 src/RuleSet/DeclarationBlock.php         |  2 +-
 src/RuleSet/RuleSet.php                  |  8 ++++----
 src/Value/CSSFunction.php                |  2 +-
 src/Value/CSSString.php                  |  2 +-
 src/Value/CalcRuleValueList.php          |  7 ++-----
 src/Value/Color.php                      |  2 +-
 src/Value/LineName.php                   |  2 +-
 src/Value/PrimitiveValue.php             |  2 +-
 src/Value/RuleValueList.php              |  2 +-
 src/Value/Size.php                       |  2 +-
 src/Value/URL.php                        |  2 +-
 src/Value/Value.php                      |  8 ++++----
 src/Value/ValueList.php                  |  7 ++-----
 31 files changed, 60 insertions(+), 72 deletions(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 72351773..38a03088 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -24,7 +24,7 @@ Please also have a look at our
 - Only allow `string` for some `OutputFormat` properties (#885)
 - Make all non-private properties `@internal` (#886)
 - Use more native type declarations and strict mode
-  (#641, #772, #774, #778, #804, #841, #873, #875)
+  (#641, #772, #774, #778, #804, #841, #873, #875, #891)
 - Add visibility to all class/interface constants (#469)
 
 ### Deprecated
diff --git a/src/CSSList/AtRuleBlockList.php b/src/CSSList/AtRuleBlockList.php
index af0adf31..25ba773c 100644
--- a/src/CSSList/AtRuleBlockList.php
+++ b/src/CSSList/AtRuleBlockList.php
@@ -25,7 +25,7 @@ class AtRuleBlockList extends CSSBlockList implements AtRule
     /**
      * @param string $type
      * @param string $arguments
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($type, $arguments = '', $lineNumber = 0)
     {
diff --git a/src/CSSList/CSSBlockList.php b/src/CSSList/CSSBlockList.php
index e72850b1..3ccab5a1 100644
--- a/src/CSSList/CSSBlockList.php
+++ b/src/CSSList/CSSBlockList.php
@@ -21,7 +21,7 @@
 abstract class CSSBlockList extends CSSList
 {
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($lineNumber = 0)
     {
diff --git a/src/CSSList/CSSList.php b/src/CSSList/CSSList.php
index 425ca5ba..35791089 100644
--- a/src/CSSList/CSSList.php
+++ b/src/CSSList/CSSList.php
@@ -48,14 +48,14 @@ abstract class CSSList implements Renderable, Commentable
     protected $contents;
 
     /**
-     * @var int
+     * @var int<0, max>
      *
      * @internal since 8.8.0
      */
     protected $lineNumber;
 
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($lineNumber = 0)
     {
@@ -255,9 +255,9 @@ private static function identifierIs($identifier, string $match): bool
     }
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo()
+    public function getLineNo(): int
     {
         return $this->lineNumber;
     }
diff --git a/src/CSSList/Document.php b/src/CSSList/Document.php
index 490a9752..51d87a4a 100644
--- a/src/CSSList/Document.php
+++ b/src/CSSList/Document.php
@@ -19,7 +19,7 @@
 class Document extends CSSBlockList
 {
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($lineNumber = 0)
     {
diff --git a/src/CSSList/KeyFrame.php b/src/CSSList/KeyFrame.php
index 61e70380..8a6bea7d 100644
--- a/src/CSSList/KeyFrame.php
+++ b/src/CSSList/KeyFrame.php
@@ -20,7 +20,7 @@ class KeyFrame extends CSSList implements AtRule
     private $animationName;
 
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($lineNumber = 0)
     {
diff --git a/src/Comment/Comment.php b/src/Comment/Comment.php
index acc0fc34..7d6de3d7 100644
--- a/src/Comment/Comment.php
+++ b/src/Comment/Comment.php
@@ -10,7 +10,7 @@
 class Comment implements Renderable
 {
     /**
-     * @var int
+     * @var int<0, max>
      *
      * @internal since 8.8.0
      */
@@ -25,7 +25,7 @@ class Comment implements Renderable
 
     /**
      * @param string $commentText
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($commentText = '', $lineNumber = 0)
     {
@@ -42,9 +42,9 @@ public function getComment()
     }
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo()
+    public function getLineNo(): int
     {
         return $this->lineNumber;
     }
diff --git a/src/Parser.php b/src/Parser.php
index 858c0d74..faaeb87d 100644
--- a/src/Parser.php
+++ b/src/Parser.php
@@ -20,7 +20,7 @@ class Parser
 
     /**
      * @param string $sText the complete CSS as text (i.e., usually the contents of a CSS file)
-     * @param int $lineNumber the line number (starting from 1, not from 0)
+     * @param int<0, max> $lineNumber the line number (starting from 1, not from 0)
      */
     public function __construct($sText, ?Settings $oParserSettings = null, $lineNumber = 1)
     {
diff --git a/src/Parsing/OutputException.php b/src/Parsing/OutputException.php
index d52d7380..63b32207 100644
--- a/src/Parsing/OutputException.php
+++ b/src/Parsing/OutputException.php
@@ -11,7 +11,7 @@ final class OutputException extends SourceException
 {
     /**
      * @param string $sMessage
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($sMessage, $lineNumber = 0)
     {
diff --git a/src/Parsing/ParserState.php b/src/Parsing/ParserState.php
index c14674d2..cb28cdb0 100644
--- a/src/Parsing/ParserState.php
+++ b/src/Parsing/ParserState.php
@@ -58,7 +58,7 @@ class ParserState
 
     /**
      * @param string $sText the complete CSS as text (i.e., usually the contents of a CSS file)
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($sText, Settings $oParserSettings, $lineNumber = 1)
     {
diff --git a/src/Parsing/SourceException.php b/src/Parsing/SourceException.php
index 77adb478..1af7affc 100644
--- a/src/Parsing/SourceException.php
+++ b/src/Parsing/SourceException.php
@@ -13,7 +13,7 @@ class SourceException extends \Exception
 
     /**
      * @param string $sMessage
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($sMessage, $lineNumber = 0)
     {
@@ -25,9 +25,9 @@ public function __construct($sMessage, $lineNumber = 0)
     }
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo()
+    public function getLineNo(): int
     {
         return $this->lineNumber;
     }
diff --git a/src/Parsing/UnexpectedTokenException.php b/src/Parsing/UnexpectedTokenException.php
index 3620ff01..441397f1 100644
--- a/src/Parsing/UnexpectedTokenException.php
+++ b/src/Parsing/UnexpectedTokenException.php
@@ -30,7 +30,7 @@ class UnexpectedTokenException extends SourceException
      * @param string $sExpected
      * @param string $sFound
      * @param string $sMatchType
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($sExpected, $sFound, $sMatchType = 'literal', $lineNumber = 0)
     {
diff --git a/src/Property/CSSNamespace.php b/src/Property/CSSNamespace.php
index 7ef5e0d5..066bede6 100644
--- a/src/Property/CSSNamespace.php
+++ b/src/Property/CSSNamespace.php
@@ -37,7 +37,7 @@ class CSSNamespace implements AtRule
     /**
      * @param string $mUrl
      * @param string|null $sPrefix
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($mUrl, $sPrefix = null, $lineNumber = 0)
     {
@@ -48,9 +48,9 @@ public function __construct($mUrl, $sPrefix = null, $lineNumber = 0)
     }
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo()
+    public function getLineNo(): int
     {
         return $this->lineNumber;
     }
diff --git a/src/Property/Charset.php b/src/Property/Charset.php
index 9e848392..90dfeabf 100644
--- a/src/Property/Charset.php
+++ b/src/Property/Charset.php
@@ -24,7 +24,7 @@ class Charset implements AtRule
     private $oCharset;
 
     /**
-     * @var int
+     * @var int<0, max>
      *
      * @internal since 8.8.0
      */
@@ -38,7 +38,7 @@ class Charset implements AtRule
     protected $comments;
 
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct(CSSString $oCharset, $lineNumber = 0)
     {
@@ -48,9 +48,9 @@ public function __construct(CSSString $oCharset, $lineNumber = 0)
     }
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo()
+    public function getLineNo(): int
     {
         return $this->lineNumber;
     }
diff --git a/src/Property/Import.php b/src/Property/Import.php
index 68c13f39..329b0337 100644
--- a/src/Property/Import.php
+++ b/src/Property/Import.php
@@ -24,7 +24,7 @@ class Import implements AtRule
     private $mediaQuery;
 
     /**
-     * @var int
+     * @var int<0, max>
      *
      * @internal since 8.8.0
      */
@@ -39,7 +39,7 @@ class Import implements AtRule
 
     /**
      * @param string $mediaQuery
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct(URL $location, $mediaQuery, $lineNumber = 0)
     {
@@ -50,9 +50,9 @@ public function __construct(URL $location, $mediaQuery, $lineNumber = 0)
     }
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo()
+    public function getLineNo(): int
     {
         return $this->lineNumber;
     }
diff --git a/src/Renderable.php b/src/Renderable.php
index fc3b8e71..fb505ec0 100644
--- a/src/Renderable.php
+++ b/src/Renderable.php
@@ -6,18 +6,12 @@
 
 interface Renderable
 {
-    /**
-     * @return string
-     */
-    public function __toString();
+    public function __toString(): string;
 
-    /**
-     * @return string
-     */
-    public function render(OutputFormat $oOutputFormat);
+    public function render(OutputFormat $oOutputFormat): string;
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo();
+    public function getLineNo(): int;
 }
diff --git a/src/Rule/Rule.php b/src/Rule/Rule.php
index d863b34c..ee15059b 100644
--- a/src/Rule/Rule.php
+++ b/src/Rule/Rule.php
@@ -62,7 +62,7 @@ class Rule implements Renderable, Commentable
 
     /**
      * @param string $sRule
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      * @param int $iColNo
      */
     public function __construct($sRule, $lineNumber = 0, $iColNo = 0)
@@ -141,9 +141,9 @@ private static function listDelimiterForRule($sRule): array
     }
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo()
+    public function getLineNo(): int
     {
         return $this->lineNumber;
     }
diff --git a/src/RuleSet/AtRuleSet.php b/src/RuleSet/AtRuleSet.php
index 4a9329a8..67b274be 100644
--- a/src/RuleSet/AtRuleSet.php
+++ b/src/RuleSet/AtRuleSet.php
@@ -28,7 +28,7 @@ class AtRuleSet extends RuleSet implements AtRule
     /**
      * @param string $sType
      * @param string $sArgs
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($sType, $sArgs = '', $lineNumber = 0)
     {
diff --git a/src/RuleSet/DeclarationBlock.php b/src/RuleSet/DeclarationBlock.php
index 231476cf..2ca5de28 100644
--- a/src/RuleSet/DeclarationBlock.php
+++ b/src/RuleSet/DeclarationBlock.php
@@ -30,7 +30,7 @@ class DeclarationBlock extends RuleSet
     private $aSelectors;
 
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($lineNumber = 0)
     {
diff --git a/src/RuleSet/RuleSet.php b/src/RuleSet/RuleSet.php
index 5f9dc99d..66a9043c 100644
--- a/src/RuleSet/RuleSet.php
+++ b/src/RuleSet/RuleSet.php
@@ -30,7 +30,7 @@ abstract class RuleSet implements Renderable, Commentable
     private $aRules;
 
     /**
-     * @var int
+     * @var int<0, max>
      *
      * @internal since 8.8.0
      */
@@ -44,7 +44,7 @@ abstract class RuleSet implements Renderable, Commentable
     protected $comments;
 
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($lineNumber = 0)
     {
@@ -94,9 +94,9 @@ public static function parseRuleSet(ParserState $parserState, RuleSet $ruleSet):
     }
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo()
+    public function getLineNo(): int
     {
         return $this->lineNumber;
     }
diff --git a/src/Value/CSSFunction.php b/src/Value/CSSFunction.php
index 37572615..44635f84 100644
--- a/src/Value/CSSFunction.php
+++ b/src/Value/CSSFunction.php
@@ -24,7 +24,7 @@ class CSSFunction extends ValueList
      * @param string $sName
      * @param RuleValueList|array<array-key, Value|string> $aArguments
      * @param string $sSeparator
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($sName, $aArguments, $sSeparator = ',', $lineNumber = 0)
     {
diff --git a/src/Value/CSSString.php b/src/Value/CSSString.php
index a1ca1c70..b0c92e4c 100644
--- a/src/Value/CSSString.php
+++ b/src/Value/CSSString.php
@@ -24,7 +24,7 @@ class CSSString extends PrimitiveValue
 
     /**
      * @param string $sString
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($sString, $lineNumber = 0)
     {
diff --git a/src/Value/CalcRuleValueList.php b/src/Value/CalcRuleValueList.php
index 508296d9..84b80ade 100644
--- a/src/Value/CalcRuleValueList.php
+++ b/src/Value/CalcRuleValueList.php
@@ -9,17 +9,14 @@
 class CalcRuleValueList extends RuleValueList
 {
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($lineNumber = 0)
     {
         parent::__construct(',', $lineNumber);
     }
 
-    /**
-     * @return string
-     */
-    public function render(OutputFormat $oOutputFormat)
+    public function render(OutputFormat $oOutputFormat): string
     {
         return $oOutputFormat->implode(' ', $this->aComponents);
     }
diff --git a/src/Value/Color.php b/src/Value/Color.php
index c4d6a4ee..48249598 100644
--- a/src/Value/Color.php
+++ b/src/Value/Color.php
@@ -17,7 +17,7 @@ class Color extends CSSFunction
 {
     /**
      * @param array<array-key, Value|string> $colorValues
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct(array $colorValues, $lineNumber = 0)
     {
diff --git a/src/Value/LineName.php b/src/Value/LineName.php
index 18a53333..6caa8617 100644
--- a/src/Value/LineName.php
+++ b/src/Value/LineName.php
@@ -13,7 +13,7 @@ class LineName extends ValueList
 {
     /**
      * @param array<int, Value|string> $aComponents
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct(array $aComponents = [], $lineNumber = 0)
     {
diff --git a/src/Value/PrimitiveValue.php b/src/Value/PrimitiveValue.php
index 4cccf35c..42728c73 100644
--- a/src/Value/PrimitiveValue.php
+++ b/src/Value/PrimitiveValue.php
@@ -7,7 +7,7 @@
 abstract class PrimitiveValue extends Value
 {
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($lineNumber = 0)
     {
diff --git a/src/Value/RuleValueList.php b/src/Value/RuleValueList.php
index b68df0ea..33f98eb1 100644
--- a/src/Value/RuleValueList.php
+++ b/src/Value/RuleValueList.php
@@ -13,7 +13,7 @@ class RuleValueList extends ValueList
 {
     /**
      * @param string $sSeparator
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($sSeparator = ',', $lineNumber = 0)
     {
diff --git a/src/Value/Size.php b/src/Value/Size.php
index 82fdc261..48ae770b 100644
--- a/src/Value/Size.php
+++ b/src/Value/Size.php
@@ -71,7 +71,7 @@ class Size extends PrimitiveValue
      * @param float|int|string $fSize
      * @param string|null $sUnit
      * @param bool $bIsColorComponent
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($fSize, $sUnit = null, $bIsColorComponent = false, $lineNumber = 0)
     {
diff --git a/src/Value/URL.php b/src/Value/URL.php
index 018abefc..1608d12d 100644
--- a/src/Value/URL.php
+++ b/src/Value/URL.php
@@ -21,7 +21,7 @@ class URL extends PrimitiveValue
     private $oURL;
 
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct(CSSString $oURL, $lineNumber = 0)
     {
diff --git a/src/Value/Value.php b/src/Value/Value.php
index 3fa7abd3..b5c20c99 100644
--- a/src/Value/Value.php
+++ b/src/Value/Value.php
@@ -17,14 +17,14 @@
 abstract class Value implements Renderable
 {
     /**
-     * @var int
+     * @var int<0, max>
      *
      * @internal since 8.8.0
      */
     protected $lineNumber;
 
     /**
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($lineNumber = 0)
     {
@@ -212,9 +212,9 @@ private static function parseUnicodeRangeValue(ParserState $parserState): string
     }
 
     /**
-     * @return int
+     * @return int<0, max>
      */
-    public function getLineNo()
+    public function getLineNo(): int
     {
         return $this->lineNumber;
     }
diff --git a/src/Value/ValueList.php b/src/Value/ValueList.php
index 683ada3d..d18ad9ef 100644
--- a/src/Value/ValueList.php
+++ b/src/Value/ValueList.php
@@ -31,7 +31,7 @@ abstract class ValueList extends Value
     /**
      * @param array<array-key, Value|string>|Value|string $aComponents
      * @param string $sSeparator
-     * @param int $lineNumber
+     * @param int<0, max> $lineNumber
      */
     public function __construct($aComponents = [], $sSeparator = ',', $lineNumber = 0)
     {
@@ -88,10 +88,7 @@ public function __toString(): string
         return $this->render(new OutputFormat());
     }
 
-    /**
-     * @return string
-     */
-    public function render(OutputFormat $oOutputFormat)
+    public function render(OutputFormat $oOutputFormat): string
     {
         return $oOutputFormat->implode(
             $oOutputFormat->spaceBeforeListArgumentSeparator($this->sSeparator) . $this->sSeparator