Add some docblocks and make sure RepositorySet/PoolBuilder accept regular rootAliases and not pre-normalized ones

src/Composer/DependencyResolver/PoolBuilder.php

@@ -34,6 +34,9 @@ class PoolBuilder
 {
     private $acceptableStabilities;
     private $stabilityFlags;
+    /**
+     * @psalm-var array<string, array<string, array{alias: string, alias_normalized: string}>>
+     */
     private $rootAliases;
     private $rootReferences;
     private $eventDispatcher;
@@ -48,11 +51,21 @@ class PoolBuilder
     private $skippedLoad = array();
     private $updateAllowWarned = array();
 
+    /**
+     * @param int[] $acceptableStabilities array of stability => BasePackage::STABILITY_* value
+     * @psalm-param array<string, int> $acceptableStabilities
+     * @param int[] $stabilityFlags an array of package name => BasePackage::STABILITY_* value
+     * @psalm-param array<string, int> $stabilityFlags
+     * @param array[] $rootAliases
+     * @psalm-param list<array{package: string, version: string, alias: string, alias_normalized: string}> $rootAliases
+     * @param string[] $rootReferences an array of package name => source reference
+     * @psalm-param array<string, string> $rootReferences
+     */
     public function __construct(array $acceptableStabilities, array $stabilityFlags, array $rootAliases, array $rootReferences, IOInterface $io, EventDispatcher $eventDispatcher = null)
     {
         $this->acceptableStabilities = $acceptableStabilities;
         $this->stabilityFlags = $stabilityFlags;
-        $this->rootAliases = $rootAliases;
+        $this->rootAliases = $this->getRootAliasesPerPackage($rootAliases);
         $this->rootReferences = $rootReferences;
         $this->eventDispatcher = $eventDispatcher;
         $this->io = $io;
@@ -372,5 +385,19 @@ class PoolBuilder
         unset($this->skippedLoad[$name]);
         unset($this->loadedNames[$name]);
     }
+
+    private function getRootAliasesPerPackage(array $aliases)
+    {
+        $normalizedAliases = array();
+
+        foreach ($aliases as $alias) {
+            $normalizedAliases[$alias['package']][$alias['version']] = array(
+                'alias' => $alias['alias'],
+                'alias_normalized' => $alias['alias_normalized'],
+            );
+        }
+
+        return $normalizedAliases;
+    }
 }
 

src/Composer/Installer.php

@@ -375,14 +375,13 @@ class Installer
 
         $this->io->writeError('<info>Updating dependencies</info>');
 
-        $links = array_merge($this->package->getRequires(), $this->package->getDevRequires());
-
         // if we're updating mirrors we want to keep exactly the same versions installed which are in the lock file, but we want current remote metadata
         if ($this->updateMirrors) {
             foreach ($lockedRepository->getPackages() as $lockedPackage) {
                 $request->requireName($lockedPackage->getName(), new Constraint('==', $lockedPackage->getVersion()));
             }
         } else {
+            $links = array_merge($this->package->getRequires(), $this->package->getDevRequires());
             foreach ($links as $link) {
                 $request->requireName($link->getTarget(), $link->getConstraint());
             }
@@ -824,16 +823,7 @@ class Installer
             $aliases = $this->locker->getAliases();
         }
 
-        $normalizedAliases = array();
-
-        foreach ($aliases as $alias) {
-            $normalizedAliases[$alias['package']][$alias['version']] = array(
-                'alias' => $alias['alias'],
-                'alias_normalized' => $alias['alias_normalized'],
-            );
-        }
-
-        return $normalizedAliases;
+        return $aliases;
     }
 
     /**

src/Composer/Plugin/PrePoolCreateEvent.php

@@ -109,7 +109,8 @@ class PrePoolCreateEvent extends Event
     }
 
     /**
-     * @return array
+     * @return array[] of package => version => [alias, alias_normalized]
+     * @psalm-return array<string, array<string, array{alias: string, alias_normalized: string}>>
      */
     public function getRootAliases()
     {

src/Composer/Repository/RepositorySet.php

@@ -42,16 +42,33 @@ class RepositorySet
      */
     const ALLOW_SHADOWED_REPOSITORIES = 2;
 
-    /** @var array */
+    /**
+     * @var array[]
+     * @psalm-var list<array{package: string, version: string, alias: string, alias_normalized: string}>
+     */
     private $rootAliases;
-    /** @var array */
+
+    /**
+     * @var string[]
+     * @psalm-var array<string, string>
+     */
     private $rootReferences;
 
     /** @var RepositoryInterface[] */
     private $repositories = array();
 
+    /**
+     * @var int[] array of stability => BasePackage::STABILITY_* value
+     * @psalm-var array<string, int>
+     */
     private $acceptableStabilities;
+
+    /**
+     * @var int[] array of package name => BasePackage::STABILITY_* value
+     * @psalm-var array<string, int>
+     */
     private $stabilityFlags;
+
     private $rootRequires;
 
     /** @var bool */
@@ -59,6 +76,19 @@ class RepositorySet
     /** @var bool */
     private $allowInstalledRepositories = false;
 
+    /**
+     * In most cases if you are looking to use this class as a way to find packages from repositories
+     * passing minimumStability is all you need to worry about. The rest is for advanced pool creation including
+     * aliases, pinned references and other special cases.
+     *
+     * @param string $minimumStability
+     * @param int[] $stabilityFlags an array of package name => BasePackage::STABILITY_* value
+     * @psalm-param array<string, int> $stabilityFlags
+     * @param array[] $rootAliases
+     * @psalm-param list<array{package: string, version: string, alias: string, alias_normalized: string}> $rootAliases
+     * @param string[] $rootReferences an array of package name => source reference
+     * @psalm-param array<string, string> $rootReferences
+     */
     public function __construct($minimumStability = 'stable', array $stabilityFlags = array(), array $rootAliases = array(), array $rootReferences = array(), array $rootRequires = array())
     {
         $this->rootAliases = $rootAliases;