feature #845 Merge-powered recipe update system (weaverryan)

This PR was squashed before being merged into the 1.x branch.

Discussion
----------

Merge-powered recipe update system

Hi!

tl;dr; Updating recipes was a pain. Now its easy: the new `recipes:update` command performs a smart "patch" to your project of what actually changed in the recipe.

[![asciicast](https://asciinema.org/a/456707.svg)](https://asciinema.org/a/456707)

If you run simply `composer recipes:update`, then it will ask you what to update, from a list of only the out-dated recipes (thanks to @shadowc for the idea!):

<img width="696" alt="Screen Shot 2021-12-17 at 11 18 09 AM" src="https://user-images.githubusercontent.com/121003/146575617-8ca7c6c8-1897-4fb4-be33-cdd5bf6894c0.png">

As you can see, if there are conflicts, you fix them like normal git conflicts. In addition to the unit tests, I've tried this on a fairly out-dated project and it worked *brilliantly*. This was NOT possible until @nicolas-grekas open sourced the Flex server - so a HUGE thanks 🎆

### How It Works

A) Whenever `symfony/recipes` (or contrib) has a new commit, a GitHub action *already* stores each recipe as JSON, which becomes the "recipe API": https://github.com/symfony/recipes/tree/flex/main. A change to that action (symfony/recipes#1037) and the recipes-checker (symfony-tools/recipes-checker#2) will add an "archived/" directory that contains EVERY version of every recipe. You can see an example in my fork: https://github.com/weaverryan/recipes/tree/flex/main/archived

B) When you run `recipes:update <package/name>`, we fetch the "original" recipe and "new" recipe and then pass both to each "configurator". Its job is to say what files would exist and what they would look if the "original" recipe were installed now and if the "new" recipe were installed now.

C) We use these "original files" and "new files" to generate a patch file.

D) We apply that patch file to the user's actual project. There are a few tricks here, like temporarily inserting the git "blob" for what the "original" version of the file would look like. That allows for a 3-way merge.

So, while it was a bit of work, it's a fairly straightforward process. It makes keeping your recipes up to date both easy and rewarding.

## TODOS

* [x] Merge recipes-checker PR symfony-tools/recipes-checker#2
* [x] Merge symfony/recipes PR symfony/recipes#1037
* [x] Update `Downloader` in this PR to remove 2x TODOs that the above PR's will enable
* [x] Make sure the `archived/` directory is populated for both `recipes` and `recipes-contrib` - see symfony-tools/recipes-checker#3 and symfony/recipes#1038
* [x] Document that this now exists symfony/symfony-docs#16301

Cheers!

Commits
-------

3ee7719 Merge-powered recipe update system

Author: fabpot

.php_cs.dist .php-cs-fixer.dist.php.php_cs.dist renamed to .php-cs-fixer.dist.php

@@ -2,7 +2,7 @@
 
 $finder = PhpCsFixer\Finder::create()->in(__DIR__);
 
-return PhpCsFixer\Config::create()
+return (new PhpCsFixer\Config())
     ->setFinder($finder)
     ->setRules(array(
         '@Symfony' => true,

src/Command/InstallRecipesCommand.php

@@ -13,17 +13,17 @@
 
 use Composer\Command\BaseCommand;
 use Composer\DependencyResolver\Operation\InstallOperation;
-use Composer\Factory;
 use Symfony\Component\Console\Exception\RuntimeException;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
 use Symfony\Flex\Event\UpdateEvent;
-use Symfony\Flex\Lock;
+use Symfony\Flex\Flex;
 
 class InstallRecipesCommand extends BaseCommand
 {
+    /** @var Flex */
     private $flex;
     private $rootDir;
 
@@ -55,7 +55,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             throw new RuntimeException('Cannot run "sync-recipes --force": git not found.');
         }
 
-        $symfonyLock = new Lock(getenv('SYMFONY_LOCKFILE') ?: str_replace('composer.json', 'symfony.lock', Factory::getComposerFile()));
+        $symfonyLock = $this->flex->getLock();
         $composer = $this->getComposer();
         $locker = $composer->getLocker();
         $lockData = $locker->getLockData();

src/Command/RecipesCommand.php

@@ -13,11 +13,11 @@
 
 use Composer\Command\BaseCommand;
 use Composer\Downloader\TransportException;
-use Composer\Util\HttpDownloader;
 use Symfony\Component\Console\Input\InputArgument;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Input\InputOption;
 use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Flex\GithubApi;
 use Symfony\Flex\InformationOperation;
 use Symfony\Flex\Lock;
 use Symfony\Flex\Recipe;
@@ -31,13 +31,13 @@ class RecipesCommand extends BaseCommand
     private $flex;
 
     private $symfonyLock;
-    private $downloader;
+    private $githubApi;
 
     public function __construct(/* cannot be type-hinted */ $flex, Lock $symfonyLock, $downloader)
     {
         $this->flex = $flex;
         $this->symfonyLock = $symfonyLock;
-        $this->downloader = $downloader;
+        $this->githubApi = new GithubApi($downloader);
 
         parent::__construct();
     }
@@ -136,7 +136,7 @@ protected function execute(InputInterface $input, OutputInterface $output)
             '',
             'Run:',
             ' * <info>composer recipes vendor/package</info> to see details about a recipe.',
-            ' * <info>composer recipes:install vendor/package --force -v</info> to update that recipe.',
+            ' * <info>composer recipes:update vendor/package</info> to update that recipe.',
             '',
         ]));
 
@@ -171,13 +171,15 @@ private function displayPackageInformation(Recipe $recipe)
         $commitDate = null;
         if (null !== $lockRef && null !== $lockRepo) {
             try {
-                list($gitSha, $commitDate) = $this->findRecipeCommitDataFromTreeRef(
+                $recipeCommitData = $this->githubApi->findRecipeCommitDataFromTreeRef(
                     $recipe->getName(),
                     $lockRepo,
                     $lockBranch ?? '',
                     $lockVersion,
                     $lockRef
                 );
+                $gitSha = $recipeCommitData ? $recipeCommitData['commit'] : null;
+                $commitDate = $recipeCommitData ? $recipeCommitData['date'] : null;
             } catch (TransportException $exception) {
                 $io->writeError('Error downloading exact git sha for installed recipe.');
             }
@@ -232,7 +234,7 @@ private function displayPackageInformation(Recipe $recipe)
             $io->write([
                 '',
                 'Update this recipe by running:',
-                sprintf('<info>composer recipes:install %s --force -v</info>', $recipe->getName()),
+                sprintf('<info>composer recipes:update %s</info>', $recipe->getName()),
             ]);
         }
     }
@@ -324,63 +326,4 @@ private function writeTreeLine($line)
 
         $io->write($line);
     }
-
-    /**
-     * Attempts to find the original git sha when the recipe was installed.
-     */
-    private function findRecipeCommitDataFromTreeRef(string $package, string $repo, string $branch, string $version, string $lockRef)
-    {
-        // only supports public repository placement
-        if (0 !== strpos($repo, 'github.com')) {
-            return [null, null];
-        }
-
-        $parts = explode('/', $repo);
-        if (3 !== \count($parts)) {
-            return [null, null];
-        }
-
-        $recipePath = sprintf('%s/%s', $package, $version);
-        $commitsData = $this->requestGitHubApi(sprintf(
-            'https://api.github.com/repos/%s/%s/commits?path=%s&sha=%s',
-            $parts[1],
-            $parts[2],
-            $recipePath,
-            $branch
-        ));
-
-        foreach ($commitsData as $commitData) {
-            // go back the commits one-by-one
-            $treeUrl = $commitData['commit']['tree']['url'].'?recursive=true';
-
-            // fetch the full tree, then look for the tree for the package path
-            $treeData = $this->requestGitHubApi($treeUrl);
-            foreach ($treeData['tree'] as $treeItem) {
-                if ($treeItem['path'] !== $recipePath) {
-                    continue;
-                }
-
-                if ($treeItem['sha'] === $lockRef) {
-                    // shorten for brevity
-                    return [
-                        substr($commitData['sha'], 0, 7),
-                        $commitData['commit']['committer']['date'],
-                    ];
-                }
-            }
-        }
-
-        return [null, null];
-    }
-
-    private function requestGitHubApi(string $path)
-    {
-        if ($this->downloader instanceof HttpDownloader) {
-            $contents = $this->downloader->get($path)->getBody();
-        } else {
-            $contents = $this->downloader->getContents('api.github.com', $path, false);
-        }
-
-        return json_decode($contents, true);
-    }
 }