feat(documentator): Required requirements for Requirements command …

…can be specified in `metadata.json`.
LastDragon-ru · Aug 28, 2023 · bdb767f · bdb767f
1 parent e69abd8
commit bdb767f
Show file tree

Hide file tree

Showing 3 changed files with 69 additions and 12 deletions.
diff --git a/packages/documentator/docs/commands/requirements.md b/packages/documentator/docs/commands/requirements.md
@@ -8,6 +8,20 @@ Generates a table with the required versions of PHP/Laravel in Markdown format.
 
 * `lara-asp-documentator:requirements [<cwd>]`
 
+## Description
+
+Requirements will be cached into `<cwd>/metadata.json`. You can also use
+this file to specify the required requirements. For example, to include
+PHP only:
+
+```json
+{
+    "require": {
+        "php": "PHP"
+    }
+}
+```
+
 ## Arguments
 
 ### `cwd?`

diff --git a/packages/documentator/src/Commands/Requirements.php b/packages/documentator/src/Commands/Requirements.php
@@ -9,15 +9,16 @@
 use LastDragon_ru\LaraASP\Documentator\Metadata\Storage;
 use LastDragon_ru\LaraASP\Documentator\Package;
 use LastDragon_ru\LaraASP\Documentator\Utils\Git;
+use LastDragon_ru\LaraASP\Documentator\Utils\Path;
 use LastDragon_ru\LaraASP\Documentator\Utils\Version;
 use LastDragon_ru\LaraASP\Serializer\Contracts\Serializer;
 use Symfony\Component\Console\Attribute\AsCommand;
 
 use function array_combine;
-use function array_fill_keys;
-use function array_intersect_key;
 use function array_keys;
+use function array_merge;
 use function array_search;
+use function array_unique;
 use function assert;
 use function count;
 use function end;
@@ -48,16 +49,33 @@ class Requirements extends Command {
         {cwd? : working directory (should be a git repository)}
     SIGNATURE;
 
+    /**
+     * @phpcsSuppress SlevomatCodingStandard.TypeHints.PropertyTypeHint.MissingNativeTypeHint
+     * @var string
+     */
+    protected $help = <<<'HELP'
+        Requirements will be cached into `<cwd>/metadata.json`. You can also use
+        this file to specify the required requirements. For example, to include
+        PHP only:
+
+        ```json
+        {
+            "require": {
+                "php": "PHP"
+            }
+        }
+        ```
+        HELP;
+
     public function __invoke(Git $git, Serializer $serializer): void {
         // Get Versions
-        $cwd    = Cast::toString($this->argument('cwd') ?? getcwd());
-        $tags   = $git->getTags(Version::isVersion(...), $cwd);
-        $tags[] = 'HEAD';
+        $cwd  = Cast::toString($this->argument('cwd') ?? getcwd());
+        $tags = $this->getPackageVersions($git, $cwd, ['HEAD']);
 
         // Collect requirements
         $storage  = new Storage($serializer, $cwd);
         $metadata = $storage->load();
-        $packages = [
+        $packages = $metadata->require ?: [
             'php'               => 'PHP',
             'laravel/framework' => 'Laravel',
         ];
@@ -72,7 +90,7 @@ public function __invoke(Git $git, Serializer $serializer): void {
             $package = $this->getPackageInfo($git, $tag, $cwd);
 
             if (!$package) {
-                continue;
+                break;
             }
 
             // Update
@@ -84,10 +102,18 @@ public function __invoke(Git $git, Serializer $serializer): void {
         }
 
         // Cleanup
-        $metadata->requirements = array_intersect_key(
-            $metadata->requirements,
-            array_fill_keys($tags, null),
-        );
+        foreach ($metadata->requirements as $tag => $requirement) {
+            if (!isset($tags[$tag])) {
+                unset($metadata->requirements[$tag]);
+                break;
+            }
+
+            foreach ($requirement as $package => $versions) {
+                if (!isset($packages[$package])) {
+                    unset($metadata->requirements[$tag][$package]);
+                }
+            }
+        }
 
         // Save
         $storage->save($metadata);
@@ -106,12 +132,27 @@ public function __invoke(Git $git, Serializer $serializer): void {
         $this->output->writeln($output);
     }
 
+    /**
+     * @param list<string> $tags
+     *
+     * @return array<string, string>
+     */
+    protected function getPackageVersions(Git $git, string $cwd, array $tags = []): array {
+        $tags = array_merge($tags, $git->getTags(Version::isVersion(...), $cwd));
+        $tags = array_unique($tags);
+        $tags = array_combine($tags, $tags);
+
+        uksort($tags, static fn($a, $b) => -Version::compare($a, $b));
+
+        return $tags;
+    }
+
     /**
      * @return array<array-key, mixed>|null
      */
     protected function getPackageInfo(Git $git, string $tag, string $cwd): ?array {
         try {
-            $package = $git->getFile('composer.json', $tag, $cwd);
+            $package = $git->getFile(Path::join($cwd, 'composer.json'), $tag, $cwd);
             $package = json_decode($package, true, flags: JSON_THROW_ON_ERROR);
 
             assert(is_array($package));

diff --git a/packages/documentator/src/Metadata/Metadata.php b/packages/documentator/src/Metadata/Metadata.php
@@ -9,10 +9,12 @@
  */
 class Metadata implements Serializable {
     /**
+     * @param array<string, string>                      $require
      * @param array<string, array<string, list<string>>> $requirements
      */
     public function __construct(
         public string $version = '0.0.0',
+        public array $require = [],
         public array $requirements = [],
     ) {
         // empty