Merge branch 'cleanup'

Author: lkrms

lk-util/Command/Generate/Concept/GenerateCommand.php

@@ -66,15 +66,15 @@ abstract class GenerateCommand extends Command
      *
      * Generators should apply a default description if `null`.
      */
-    protected ?string $Description;
+    protected ?string $Description = null;
 
-    protected ?bool $ToStdout;
+    protected bool $ApiTag = false;
 
-    protected ?bool $ReplaceIfExists;
+    protected bool $ToStdout = false;
 
-    protected ?bool $Check;
+    protected bool $Check = false;
 
-    protected ?bool $NoMetaTags;
+    protected bool $ReplaceIfExists = false;
 
     // --
 
@@ -230,6 +230,11 @@ protected function getOutputOptionList(
         }
         return [
             ...$options,
+            CliOption::build()
+                ->long('api')
+                ->short('a')
+                ->description("Add an `@api` tag to the $outputType")
+                ->bindTo($this->ApiTag),
             CliOption::build()
                 ->long('stdout')
                 ->short('s')
@@ -244,26 +249,6 @@ protected function getOutputOptionList(
                 ->short('f')
                 ->description('Overwrite the output file if it already exists')
                 ->bindTo($this->ReplaceIfExists),
-            CliOption::build()
-                ->long('no-meta')
-                ->short('m')
-                ->description('Suppress metadata tags')
-                ->bindTo($this->NoMetaTags),
-        ];
-    }
-
-    /**
-     * Get an array of values to use with getEffectiveCommandLine() when
-     * generating repeatable commands
-     *
-     * @return array<string,null>
-     */
-    protected function outputOptionValues(): array
-    {
-        return [
-            'stdout' => null,
-            'check' => null,
-            'force' => null,
         ];
     }
 
@@ -538,6 +523,8 @@ protected function generate(array $innerBlocks = []): string
         $phpDoc = Arr::trimAndImplode($blank, [
             $this->Description ?? '',
             $this->PhpDoc ?? '',
+            $this->ApiTag ? '@api' : '',
+            '@generated',
         ]);
 
         $lines =

lk-util/Command/Generate/GenerateBuilder.php

@@ -43,23 +43,23 @@ class GenerateBuilder extends GenerateCommand
         'withRefB',
     ];
 
-    private ?string $ClassFqcn;
+    private string $ClassFqcn = '';
 
-    private ?string $BuilderFqcn;
+    private ?string $BuilderFqcn = null;
+
+    private bool $IncludeProperties = false;
+
+    private bool $IgnoreProperties = false;
 
     /**
      * @var string[]|null
      */
-    private ?array $Forward;
-
-    private ?bool $IncludeProperties;
-
-    private ?bool $IgnoreProperties;
+    private ?array $Forward = null;
 
     /**
-     * @var string[]|null
+     * @var string[]
      */
-    private ?array $Skip;
+    private array $Skip = [];
 
     // --
 
@@ -105,7 +105,7 @@ protected function getOptionList(): array
 
                     By default, if a property with the same name as a constructor parameter has a
                     DocBlock, its description is used in the absence of a parameter description,
-                    even if `--properties/-r` is not given. Use this option to disable this
+                    even if `-r/--properties` is not given. Use this option to disable this
                     behaviour.
                     EOF)
                 ->bindTo($this->IgnoreProperties),
@@ -120,6 +120,7 @@ protected function getOptionList(): array
                     EOF)
                 ->optionType(CliOptionType::VALUE_OPTIONAL)
                 ->multipleAllowed()
+                ->nullable()
                 ->bindTo($this->Forward),
             CliOption::build()
                 ->long('skip')
@@ -731,17 +732,14 @@ protected function run(string ...$args)
             $docBlock[] = ' *';
         }
         $docBlock[] = $methods;
-        $docBlock[] = ' *';
-        $docBlock[] = " * @uses $service";
-        $docBlock[] = ' *';
-        $docBlock[] = " * @extends $extends<$service{$this->InputClassType}>";
-        if (!$this->NoMetaTags) {
-            $command = $this->getEffectiveCommandLine(true, $this->outputOptionValues());
-            $program = array_shift($command);
+        if ($this->ApiTag) {
             $docBlock[] = ' *';
-            $docBlock[] = ' * @generated by ' . $program;
-            $docBlock[] = ' * @salient-generate-command ' . implode(' ', $command);
+            $docBlock[] = ' * @api';
         }
+        $docBlock[] = ' *';
+        $docBlock[] = " * @extends $extends<$service{$this->InputClassType}>";
+        $docBlock[] = ' *';
+        $docBlock[] = ' * @generated';
         $docBlock[] = ' */';
 
         $imports = $this->generateImports();

lk-util/Command/Generate/GenerateFacade.php

@@ -32,13 +32,14 @@ final class GenerateFacade extends GenerateCommand
         'getInstance',
     ];
 
-    private ?string $ClassFqcn;
-    private ?string $FacadeFqcn;
+    private string $ClassFqcn = '';
+
+    private string $FacadeFqcn = '';
 
     /**
-     * @var string[]|null
+     * @var string[]
      */
-    private ?array $SkipMethods;
+    private array $SkipMethods = [];
 
     public function description(): string
     {
@@ -306,16 +307,13 @@ protected function run(string ...$args)
             $docBlock[] = $methods;
             $docBlock[] = ' *';
         }
-        $docBlock[] = " * @uses $service";
-        $docBlock[] = ' *';
-        $docBlock[] = " * @extends $extends<$service>";
-        if (!$this->NoMetaTags) {
-            $command = $this->getEffectiveCommandLine(true, $this->outputOptionValues());
-            $program = array_shift($command);
+        if ($this->ApiTag) {
+            $docBlock[] = ' * @api';
             $docBlock[] = ' *';
-            $docBlock[] = ' * @generated by ' . $program;
-            $docBlock[] = ' * @salient-generate-command ' . implode(' ', $command);
         }
+        $docBlock[] = " * @extends $extends<$service>";
+        $docBlock[] = ' *';
+        $docBlock[] = ' * @generated';
         $docBlock[] = ' */';
 
         $blocks = [

lk-util/Command/Generate/GenerateSyncEntity.php

@@ -3,6 +3,7 @@
 namespace Lkrms\LkUtil\Command\Generate;
 
 use Lkrms\Cli\Catalog\CliOptionType;
+use Lkrms\Cli\Catalog\CliOptionValueType;
 use Lkrms\Cli\Exception\CliInvalidArgumentsException;
 use Lkrms\Cli\CliOption;
 use Lkrms\Concern\HasParent;
@@ -30,46 +31,46 @@ class GenerateSyncEntity extends GenerateCommand
      */
     public ?array $Entity;
 
-    private ?string $ClassFqcn;
+    private string $ClassFqcn = '';
 
-    private ?string $MemberVisibility;
+    private string $MemberVisibility = '';
 
     /**
-     * @var string[]|null
+     * @var string[]
      */
-    private ?array $OneToOneRelationships;
+    private array $OneToOneRelationships = [];
 
     /**
-     * @var string[]|null
+     * @var string[]
      */
-    private ?array $OneToManyRelationships;
+    private array $OneToManyRelationships = [];
 
-    private ?string $ParentProperty;
+    private ?string $ParentProperty = null;
 
-    private ?string $ChildrenProperty;
+    private ?string $ChildrenProperty = null;
 
-    private ?string $ReferenceEntityFile;
+    private ?string $ReferenceEntityFile = null;
 
     /**
      * @var class-string<HttpSyncProvider>|null
      */
-    private ?string $Provider;
+    private ?string $Provider = null;
 
-    private ?string $HttpEndpoint;
+    private ?string $HttpEndpoint = null;
 
-    private ?string $HttpMethod;
+    private string $HttpMethod = '';
 
     /**
-     * @var string[]|null
+     * @var string[]
      */
-    private ?array $HttpQuery;
+    private array $HttpQuery = [];
 
-    private ?string $HttpDataFile;
+    private ?string $HttpDataFile = null;
 
     /**
-     * @var string[]|null
+     * @var string[]
      */
-    private ?array $SkipProperties;
+    private array $SkipProperties = [];
 
     public function description(): string
     {
@@ -135,6 +136,7 @@ protected function getOptionList(): array
                 ->valueName('file')
                 ->description('The path to a JSON-serialized reference entity')
                 ->optionType(CliOptionType::VALUE)
+                ->valueType(CliOptionValueType::FILE)
                 ->bindTo($this->ReferenceEntityFile),
             CliOption::build()
                 ->long('provider')
@@ -177,6 +179,7 @@ protected function getOptionList(): array
                 ->valueName('file')
                 ->description('The path to JSON-serialized data to submit when requesting a reference entity')
                 ->optionType(CliOptionType::VALUE)
+                ->valueType(CliOptionValueType::FILE)
                 ->bindTo($this->HttpDataFile),
             CliOption::build()
                 ->long('skip')
@@ -250,15 +253,6 @@ protected function run(string ...$args)
         $data = null;
         $dataUri = null;
 
-        $values = $this->outputOptionValues() + [
-            'json' => null,
-            'provider' => null,
-            'endpoint' => null,
-            'method' => null,
-            'query' => null,
-            'data' => null,
-        ];
-
         if ($json !== null) {
             $entity = $this->getJson($json, $entityUri);
             if (!is_array($entity)) {
@@ -316,9 +310,6 @@ protected static function getRemovablePrefixes(): ?array
         foreach ($this->SkipProperties as $property) {
             $skip[] = $normaliser($property);
         }
-        if ($skip) {
-            $values['skip'] = $skip;
-        }
 
         if ($entity) {
             foreach (['data', 'Result', 'Items'] as $property) {
@@ -389,16 +380,16 @@ protected static function getRemovablePrefixes(): ?array
 
         $count = 0;
         if ($this->ParentProperty !== null) {
-            $this->validateRelationship("{$this->ParentProperty}={$class}", $normaliser, $parent, $values['parent'], true);
-            $this->validateRelationship("{$this->ChildrenProperty}={$class}", $normaliser, $children, $values['children'], true);
+            $this->validateRelationship("{$this->ParentProperty}={$class}", $normaliser, $parent);
+            $this->validateRelationship("{$this->ChildrenProperty}={$class}", $normaliser, $children);
             $count += 2;
         }
         foreach ($this->OneToOneRelationships as $value) {
-            $this->validateRelationship($value, $normaliser, $oneToOne, $values['one']);
+            $this->validateRelationship($value, $normaliser, $oneToOne);
             $count++;
         }
         foreach ($this->OneToManyRelationships as $value) {
-            $this->validateRelationship($value, $normaliser, $oneToMany, $values['many']);
+            $this->validateRelationship($value, $normaliser, $oneToMany);
             $count++;
         }
         if (count($oneToOne + $oneToMany + $parent + $children) !== $count) {
@@ -438,23 +429,6 @@ protected static function getRemovablePrefixes(): ?array
             $docBlock[] = '';
         }
 
-        if (!$this->NoMetaTags) {
-            if ($provider) {
-                unset($values['provider']);
-            }
-            if ($json !== null) {
-                $values['json'] = $entityUri ?? $this->ReferenceEntityFile;
-            } elseif ($provider) {
-                unset($values['endpoint'], $values['query']);
-                $values['method'] = $method ?? null;
-                $values['data'] = $dataUri ?? $this->HttpDataFile;
-            }
-            $command = $this->getEffectiveCommandLine(true, $values);
-            $program = array_shift($command);
-            $docBlock[] = '@generated by ' . $program;
-            $docBlock[] = '@salient-generate-command ' . implode(' ', $command);
-        }
-
         if ($docBlock) {
             $this->PhpDoc = implode(\PHP_EOL, $docBlock);
         }
@@ -514,9 +488,7 @@ protected static function getRemovablePrefixes(): ?array
     private function validateRelationship(
         string $relationship,
         Closure $normaliser,
-        array &$array,
-        ?string &$value = null,
-        bool $isParentOrChildren = false
+        array &$array
     ): void {
         if (!Pcre::match(
             '/^(?<property>[[:alpha:]_][[:alnum:]_]*)=(?<class>[[:alpha:]_][[:alnum:]_]*)$/i',
@@ -532,10 +504,5 @@ private function validateRelationship(
         $property = $normaliser($matches['property']);
         $class = $normaliser($matches['class']);
         $array[$property] = $class;
-
-        $value =
-            ($value === null ? '' : "$value,")
-            . $property
-            . ($isParentOrChildren ? '' : "={$class}");
     }
 }