Add DevTools self-update command

Author: coisa

src/Composer/Command/ProxyCommand.php

@@ -48,10 +48,12 @@ public function __construct(
     }
 
     /**
-     * @param InputInterface $input
-     * @param OutputInterface $output
+     * Executes the proxied Symfony command through Composer's command contract.
      *
-     * @return int
+     * @param InputInterface $input the Composer command input
+     * @param OutputInterface $output the Composer command output
+     *
+     * @return int the proxied command status code
      */
     protected function execute(InputInterface $input, OutputInterface $output): int
     {

src/Composer/DevToolsPluginInterface.php

@@ -26,6 +26,9 @@
  */
 interface DevToolsPluginInterface extends PluginInterface
 {
+    /**
+     * @var list<string> composer command names and aliases that DevTools MUST NOT override
+     */
     public const array COMPOSER_COMMAND_NAMES = [
         '_complete',
         'about',

src/Reflection/ClassReflection.php

@@ -24,12 +24,19 @@
 
 /**
  * Centralizes small reflection lookups used by DevTools runtime metadata.
+ *
+ * This helper keeps command discovery code focused on command behavior instead of
+ * raw reflection boilerplate.
  */
 final class ClassReflection
 {
     /**
-     * @param class-string $className
-     * @param class-string $parentClass
+     * Detects whether a class can be instantiated as a subclass of another class.
+     *
+     * @param class-string $className the class being inspected
+     * @param class-string $parentClass the required parent class or interface
+     *
+     * @return bool true when the class is instantiable and extends or implements the expected parent
      */
     public static function isInstantiableSubclassOf(string $className, string $parentClass): bool
     {
@@ -39,10 +46,15 @@ public static function isInstantiableSubclassOf(string $className, string $paren
     }
 
     /**
-     * @param class-string $className
-     * @param class-string $attributeClass
+     * Returns the first matching attribute arguments normalized by constructor parameter name.
+     *
+     * Positional arguments are mapped to their constructor parameter names so callers do not
+     * need to understand how the attribute was declared at the call site.
+     *
+     * @param class-string $className the class being inspected
+     * @param class-string $attributeClass the attribute class being read
      *
-     * @return array<string, mixed>|null
+     * @return array<string, mixed>|null the normalized argument map, or null when the attribute is absent
      */
     public static function getAttributeArguments(string $className, string $attributeClass): ?array
     {

tests/Console/Command/SelfUpdateCommandTest.php

@@ -42,12 +42,24 @@ final class SelfUpdateCommandTest extends TestCase
 {
     use ProphecyTrait;
 
+    /**
+     * @var ObjectProphecy<SelfUpdateRunnerInterface>
+     */
     private ObjectProphecy $selfUpdateRunner;
 
+    /**
+     * @var ObjectProphecy<LoggerInterface>
+     */
     private ObjectProphecy $logger;
 
+    /**
+     * @var ObjectProphecy<InputInterface>
+     */
     private ObjectProphecy $input;
 
+    /**
+     * @var ObjectProphecy<OutputInterface>
+     */
     private ObjectProphecy $output;
 
     private SelfUpdateCommand $command;

tests/Reflection/ClassReflectionTest.php

@@ -90,5 +90,8 @@ public function getAttributeArgumentsWillNormalizePositionalArguments(): void
     }
 }
 
+/**
+ * Fixture command that declares AsCommand through positional arguments.
+ */
 #[AsCommand('fixture', 'Fixture command.', ['alias'])]
 final class FixtureCommandWithPositionalAttribute extends Command {}

tests/SelfUpdate/ComposerSelfUpdateRunnerTest.php

@@ -35,12 +35,24 @@ final class ComposerSelfUpdateRunnerTest extends TestCase
 {
     use ProphecyTrait;
 
+    /**
+     * @var ObjectProphecy<ProcessBuilderInterface>
+     */
     private ObjectProphecy $processBuilder;
 
+    /**
+     * @var ObjectProphecy<ProcessQueueInterface>
+     */
     private ObjectProphecy $processQueue;
 
+    /**
+     * @var ObjectProphecy<Process>
+     */
     private ObjectProphecy $process;
 
+    /**
+     * @var ObjectProphecy<OutputInterface>
+     */
     private ObjectProphecy $output;
 
     private ComposerSelfUpdateRunner $runner;

tests/SelfUpdate/VersionCheckNotifierTest.php

@@ -38,8 +38,14 @@ final class VersionCheckNotifierTest extends TestCase
 {
     use ProphecyTrait;
 
+    /**
+     * @var ObjectProphecy<VersionCheckerInterface>
+     */
     private ObjectProphecy $versionChecker;
 
+    /**
+     * @var ObjectProphecy<OutputInterface>
+     */
     private ObjectProphecy $output;
 
     private VersionCheckNotifier $notifier;