Add types to `Package/Version` (#10199)

src/Composer/Package/Version/VersionGuesser.php

@@ -26,6 +26,8 @@ use Composer\Util\Svn as SvnUtil;
  *
  * @author Jordi Boggiano <j.boggiano@seld.be>
  * @author Samuel Roze <samuel.roze@gmail.com>
+ *
+ * @phpstan-type Version array{version: string, commit: string|null, pretty_version: string|null, feature_version?: string|null, feature_pretty_version?: string|null}
  */
 class VersionGuesser
 {
@@ -57,10 +59,11 @@ class VersionGuesser
     }
 
     /**
-     * @param array  $packageConfig
-     * @param string $path          Path to guess into
+     * @param array<string, mixed> $packageConfig
+     * @param string               $path Path to guess into
      *
-     * @return null|array versionData, 'version', 'pretty_version' and 'commit' keys, if the version is a feature branch, 'feature_version' and 'feature_pretty_version' keys may also be returned
+     * @return array|null
+     * @phpstan-return Version|null
      */
     public function guessVersion(array $packageConfig, $path)
     {
@@ -91,6 +94,14 @@ class VersionGuesser
         return null;
     }
 
+    /**
+     * @param array $versionData
+     *
+     * @phpstan-param Version $versionData
+     *
+     * @return array
+     * @phpstan-return Version
+     */
     private function postprocess(array $versionData)
     {
         if (!empty($versionData['feature_version']) && $versionData['feature_version'] === $versionData['version'] && $versionData['feature_pretty_version'] === $versionData['pretty_version']) {
@@ -108,6 +119,12 @@ class VersionGuesser
         return $versionData;
     }
 
+    /**
+     * @param array<string, mixed> $packageConfig
+     * @param string               $path
+     *
+     * @return array{version: string|null, commit: string|null, pretty_version: string|null, feature_version?: string|null, feature_pretty_version?: string|null}
+     */
     private function guessGitVersion(array $packageConfig, $path)
     {
         GitUtil::cleanEnv();
@@ -188,6 +205,11 @@ class VersionGuesser
         return array('version' => $version, 'commit' => $commit, 'pretty_version' => $prettyVersion);
     }
 
+    /**
+     * @param string $path
+     *
+     * @return array{version: string, pretty_version: string}|null
+     */
     private function versionFromGitTags($path)
     {
         // try to fetch current version from git tags
@@ -203,6 +225,12 @@ class VersionGuesser
         return null;
     }
 
+    /**
+     * @param array<string, mixed> $packageConfig
+     * @param string               $path
+     *
+     * @return array{version: string|null, commit: ''|null, pretty_version: string|null, feature_version?: string|null, feature_pretty_version?: string|null}|null
+     */
     private function guessHgVersion(array $packageConfig, $path)
     {
         // try to fetch current version from hg branch
@@ -232,8 +260,21 @@ class VersionGuesser
 
             return $result;
         }
+
+        return null;
     }
 
+    /**
+     * @param array<string, mixed>     $packageConfig
+     * @param string|null              $version
+     * @param string[]                 $branches
+     * @param string                   $scmCmdline
+     * @param string                   $path
+     *
+     * @phpstan-param non-empty-string $scmCmdline
+     *
+     * @return array{version: string|null, pretty_version: string|null}
+     */
     private function guessFeatureVersion(array $packageConfig, $version, array $branches, $scmCmdline, $path)
     {
         $prettyVersion = $version;
@@ -292,6 +333,12 @@ class VersionGuesser
         return array('version' => $version, 'pretty_version' => $prettyVersion);
     }
 
+    /**
+     * @param array<string, mixed> $packageConfig
+     * @param string|null          $branchName
+     *
+     * @return bool
+     */
     private function isFeatureBranch(array $packageConfig, $branchName)
     {
         $nonFeatureBranches = '';
@@ -302,6 +349,11 @@ class VersionGuesser
         return !preg_match('{^(' . $nonFeatureBranches . '|master|main|latest|next|current|support|tip|trunk|default|develop|\d+\..+)$}', $branchName, $match);
     }
 
+    /**
+     * @param string $path
+     *
+     * @return array{version: string|null, commit: '', pretty_version: string|null}
+     */
     private function guessFossilVersion($path)
     {
         $version = null;
@@ -326,6 +378,12 @@ class VersionGuesser
         return array('version' => $version, 'commit' => '', 'pretty_version' => $prettyVersion);
     }
 
+    /**
+     * @param array<string, mixed> $packageConfig
+     * @param string               $path
+     *
+     * @return array{version: string, commit: '', pretty_version: string}|null
+     */
     private function guessSvnVersion(array $packageConfig, $path)
     {
         SvnUtil::cleanEnv();
@@ -357,5 +415,7 @@ class VersionGuesser
                 return array('version' => $version, 'commit' => '', 'pretty_version' => $prettyVersion);
             }
         }
+
+        return null;
     }
 }

src/Composer/Package/Version/VersionParser.php

@@ -42,9 +42,9 @@ class VersionParser extends SemverVersionParser
      * The parsing results in an array of arrays, each of which
      * contain a 'name' key with value and optionally a 'version' key with value.
      *
-     * @param array $pairs a set of package/version pairs separated by ":", "=" or " "
+     * @param string[] $pairs a set of package/version pairs separated by ":", "=" or " "
      *
-     * @return array[] array of arrays containing a name and (if provided) a version
+     * @return list<array{name: string, version?: string}>
      */
     public function parseNameVersionPairs(array $pairs)
     {
@@ -70,6 +70,9 @@ class VersionParser extends SemverVersionParser
     }
 
     /**
+     * @param string $normalizedFrom
+     * @param string $normalizedTo
+     *
      * @return bool
      */
     public static function isUpgrade($normalizedFrom, $normalizedTo)

src/Composer/Package/Version/VersionSelector.php

@@ -57,10 +57,12 @@ class VersionSelector
      * Given a package name and optional version, returns the latest PackageInterface
      * that matches.
      *
-     * @param  string                 $packageName
-     * @param  string                 $targetPackageVersion
-     * @param  string                 $preferredStability
-     * @param  bool|array             $ignorePlatformReqs
+     * @param string        $packageName
+     * @param string        $targetPackageVersion
+     * @param string        $preferredStability
+     * @param bool|string[] $ignorePlatformReqs
+     * @param int           $repoSetFlags
+     *
      * @return PackageInterface|false
      */
     public function findBestCandidate($packageName, $targetPackageVersion = null, $preferredStability = 'stable', $ignorePlatformReqs = false, $repoSetFlags = 0)
@@ -187,6 +189,13 @@ class VersionSelector
         return $package->getPrettyVersion();
     }
 
+    /**
+     * @param string $version
+     * @param string $prettyVersion
+     * @param string $stability
+     *
+     * @return string
+     */
     private function transformVersion($version, $prettyVersion, $stability)
     {
         // attempt to transform 2.1.1 to 2.1
@@ -215,6 +224,9 @@ class VersionSelector
         return '^' . $version;
     }
 
+    /**
+     * @return VersionParser
+     */
     private function getParser()
     {
         if ($this->parser === null) {