Check for mismatches in the mixin classes

When we change the contract of a validator, or create a new one, we need to
ensure that the mixin for the validator is present and matches the validator's
constructor.

This commit changes the current class that generates those mixin classes,
converting it into a linter so we can run it in the GitHub workflow to check for
missing changes.

Author: henriquemoody

.github/workflows/continuous-integration-code.yml

@@ -89,3 +89,6 @@ jobs:
 
       - name: Run PHPStan
         run: vendor/bin/phpstan analyze
+
+      - name: Run Validator's mixin linter
+        run: bin/console lint:mixin

bin/console

@@ -10,15 +10,15 @@ declare(strict_types=1);
 
 require __DIR__ . '/../vendor/autoload.php';
 
-use Respect\Dev\Commands\CreateMixinCommand;
 use Respect\Dev\Commands\LintDocsCommand;
+use Respect\Dev\Commands\LintMixinCommand;
 use Respect\Dev\Commands\SmokeTestsCheckCompleteCommand;
 use Respect\Dev\Commands\LintSpdxCommand;
 use Respect\Dev\Commands\UpdateDomainSuffixesCommand;
 use Respect\Dev\Commands\UpdateDomainToplevelCommand;
 use Respect\Dev\Commands\UpdatePostalCodesCommand;
+use Respect\Dev\Differ\ConsoleDiffer;
 use Respect\Dev\Markdown\CompositeLinter;
-use Respect\Dev\Markdown\Differ as MarkdownDiffer;
 use Respect\Dev\Markdown\Linters\AssertionMessageLinter;
 use Respect\Dev\Markdown\Linters\ValidatorHeaderLinter;
 use Respect\Dev\Markdown\Linters\ValidatorIndexLinter;
@@ -30,10 +30,9 @@ use SebastianBergmann\Diff\Output\UnifiedDiffOutputBuilder;
 use Symfony\Component\Console\Application;
 
 return (static function () {
-    $differ = new MarkdownDiffer(new Differ(new UnifiedDiffOutputBuilder('', addLineNumbers: true)));
+    $differ = new ConsoleDiffer(new Differ(new UnifiedDiffOutputBuilder('', addLineNumbers: true)));
 
     $application = new Application('Respect/Validation', '3.0');
-    $application->addCommand(new CreateMixinCommand());
     $application->addCommand(new LintDocsCommand($differ, new CompositeLinter(
         new AssertionMessageLinter(),
         new ValidatorHeaderLinter(),
@@ -42,6 +41,7 @@ return (static function () {
         new ValidatorTemplatesLinter(),
         new ValidatorChangelogLinter(),
     )));
+    $application->addCommand(new LintMixinCommand($differ));
     $application->addCommand(new LintSpdxCommand());
     $application->addCommand(new UpdateDomainSuffixesCommand());
     $application->addCommand(new UpdateDomainToplevelCommand());

phpcs.xml.dist

@@ -26,6 +26,7 @@
         <exclude-pattern>tests/Pest.php</exclude-pattern>
     </rule>
     <rule ref="Generic.Files.LineLength.TooLong">
+        <exclude-pattern>src/Mixins/</exclude-pattern>
         <exclude-pattern>tests/feature/</exclude-pattern>
     </rule>
     <rule ref="SlevomatCodingStandard.Functions.StaticClosure.ClosureNotStatic">

src-dev/Commands/LintDocsCommand.php

@@ -10,7 +10,8 @@
 
 namespace Respect\Dev\Commands;
 
-use Respect\Dev\Markdown\Differ;
+use Respect\Dev\Differ\ConsoleDiffer;
+use Respect\Dev\Differ\Item;
 use Respect\Dev\Markdown\File;
 use Respect\Dev\Markdown\Linter;
 use Symfony\Component\Console\Attribute\AsCommand;
@@ -30,7 +31,7 @@
 final class LintDocsCommand extends Command
 {
     public function __construct(
-        private readonly Differ $differ,
+        private readonly ConsoleDiffer $differ,
         private readonly Linter $linter,
     ) {
         parent::__construct();
@@ -61,7 +62,10 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
             $lintedFiles[] = $linted;
 
-            $output->writeln($this->differ->diff($original, $linted));
+            $output->writeln($this->differ->diff(
+                new Item($original->filename, $original->content->build()),
+                new Item($linted->filename, $linted->content->build()),
+            ));
         }
 
         if ($lintedFiles === []) {

src-dev/Commands/CreateMixinCommand.php src-dev/Commands/LintMixinCommand.phpsrc-dev/Commands/CreateMixinCommand.php renamed to src-dev/Commands/LintMixinCommand.php

@@ -19,6 +19,8 @@
 use ReflectionNamedType;
 use ReflectionParameter;
 use ReflectionUnionType;
+use Respect\Dev\Differ\ConsoleDiffer;
+use Respect\Dev\Differ\Item;
 use Respect\Validation\Mixins\AllBuilder;
 use Respect\Validation\Mixins\AllChain;
 use Respect\Validation\Mixins\Chain;
@@ -44,31 +46,34 @@
 use Symfony\Component\Console\Command\Command;
 use Symfony\Component\Console\Input\InputInterface;
 use Symfony\Component\Console\Output\OutputInterface;
-use Symfony\Component\Console\Style\SymfonyStyle;
 
-use function array_filter;
+use function array_keys;
 use function array_merge;
+use function array_values;
 use function count;
 use function dirname;
-use function file_exists;
+use function file_get_contents;
 use function file_put_contents;
 use function implode;
 use function in_array;
 use function is_object;
 use function ksort;
 use function lcfirst;
+use function preg_match;
 use function preg_replace;
-use function shell_exec;
 use function sprintf;
 use function str_contains;
 use function str_starts_with;
+use function trim;
 use function ucfirst;
 
+use const PHP_EOL;
+
 #[AsCommand(
-    name: 'create:mixin',
-    description: 'Generate mixin interfaces from validators',
+    name: 'lint:mixin',
+    description: 'Apply linters to the generated mixin interfaces',
 )]
-final class CreateMixinCommand extends Command
+final class LintMixinCommand extends Command
 {
     private const array NUMBER_RELATED_VALIDATORS = [
         'Between',
@@ -109,19 +114,29 @@ final class CreateMixinCommand extends Command
         'Named',
     ];
 
-    protected function execute(InputInterface $input, OutputInterface $output): int
-    {
-        $io = new SymfonyStyle($input, $output);
+    public function __construct(
+        private readonly ConsoleDiffer $differ,
+    ) {
+        parent::__construct();
+    }
 
-        $io->title('Generating mixin interfaces');
+    protected function configure(): void
+    {
+        $this->addOption(
+            'fix',
+            null,
+            null,
+            'Automatically fix files with issues.',
+        );
+    }
 
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
         // Scan validators directory
         $srcDir = dirname(__DIR__, 2) . '/src';
         $validatorsDir = $srcDir . '/Validators';
         $validators = $this->scanValidators($validatorsDir);
 
-        $io->text(sprintf('Found %d validators', count($validators)));
-
         // Define mixins
         $mixins = [
             ['All', 'all', [], array_merge(['All'], self::STRUCTURE_RELATED_VALIDATORS)],
@@ -133,23 +148,19 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             ['NullOr', 'nullOr', [], ['NullOr', 'Blank', 'Undef', 'UndefOr', 'Templated', 'Named']],
             ['Property', 'property', [], self::STRUCTURE_RELATED_VALIDATORS],
             ['UndefOr', 'undefOr', [], ['NullOr', 'Blank', 'Undef', 'UndefOr', 'Attributes', 'Templated', 'Named']],
-            ['', null, [], []],
+            [null, null, [], []],
         ];
 
-        $io->section('Generating mixin interfaces');
+        $updatableFiles = [];
 
         foreach ($mixins as [$name, $prefix, $allowList, $denyList]) {
-            $io->text(sprintf('Generating %sBuilder and %sChain', $name ?: 'Base', $name ?: 'Base'));
-
             $chainedNamespace = new PhpNamespace('Respect\\Validation\\Mixins');
-            $chainedNamespace->addUse(Validator::class);
             $chainedInterface = $chainedNamespace->addInterface($name . 'Chain');
 
             $staticNamespace = new PhpNamespace('Respect\\Validation\\Mixins');
-            $staticNamespace->addUse(Validator::class);
             $staticInterface = $staticNamespace->addInterface($name . 'Builder');
 
-            if ($name === '') {
+            if ($name === null) {
                 $chainedInterface->addExtend(Validator::class);
                 $chainedInterface->addExtend(AllChain::class);
                 $chainedInterface->addExtend(KeyChain::class);
@@ -160,7 +171,8 @@ protected function execute(InputInterface $input, OutputInterface $output): int
                 $chainedInterface->addExtend(NullOrChain::class);
                 $chainedInterface->addExtend(PropertyChain::class);
                 $chainedInterface->addExtend(UndefOrChain::class);
-                $chainedInterface->addComment('@mixin \\' . ValidatorBuilder::class);
+                $chainedInterface->addComment('@mixin ValidatorBuilder');
+                $chainedNamespace->addUse(ValidatorBuilder::class);
 
                 $staticInterface->addExtend(AllBuilder::class);
                 $staticInterface->addExtend(KeyBuilder::class);
@@ -175,6 +187,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
 
             foreach ($validators as $originalName => $reflection) {
                 $this->addMethodToInterface(
+                    $staticNamespace,
                     $originalName,
                     $staticInterface,
                     $reflection,
@@ -183,6 +196,7 @@ protected function execute(InputInterface $input, OutputInterface $output): int
                     $denyList,
                 );
                 $this->addMethodToInterface(
+                    $chainedNamespace,
                     $originalName,
                     $chainedInterface,
                     $reflection,
@@ -193,25 +207,42 @@ protected function execute(InputInterface $input, OutputInterface $output): int
             }
 
             $printer = new Printer();
-            $printer->wrapLength = 115;
+            $printer->wrapLength = 300;
 
-            $this->overwriteFile($printer->printNamespace($staticNamespace), $staticInterface->getName());
-            $this->overwriteFile($printer->printNamespace($chainedNamespace), $chainedInterface->getName());
+            foreach (
+                [
+                    [$staticNamespace, $staticInterface],
+                    [$chainedNamespace, $chainedInterface],
+                ] as [$namespace, $interface]
+            ) {
+                $filename = sprintf('%s/Mixins/%s.php', $srcDir, $interface->getName());
+                $existingContent = file_get_contents($filename);
+                $formattedContent = $this->getFormattedContent($printer->printNamespace($namespace), $existingContent);
+                if ($formattedContent === $existingContent) {
+                    continue;
+                }
+
+                $updatableFiles[$filename] = $formattedContent;
+                $output->writeln($this->differ->diff(
+                    new Item($filename, $existingContent),
+                    new Item($filename, $formattedContent),
+                ));
+            }
         }
 
-        // Run code beautifier
-        $io->section('Running code beautifier');
-        $mixinsDir = $srcDir . '/Mixins';
-        $phpcbfPath = dirname(__DIR__, 2) . '/vendor/bin/phpcbf';
-
-        if (file_exists($phpcbfPath)) {
-            shell_exec($phpcbfPath . ' ' . $mixinsDir);
-            $io->success('Code beautified');
+        if ($updatableFiles === []) {
+            $output->writeln('<info>No changes needed.</info>');
         } else {
-            $io->warning('phpcbf not found, skipping code beautification');
+            $output->writeln(sprintf('<comment>Changes needed in %d files.</comment>', count($updatableFiles)));
         }
 
-        $io->success('Mixin interfaces generated successfully');
+        if ($updatableFiles !== [] && !$input->getOption('fix')) {
+            return Command::FAILURE;
+        }
+
+        foreach ($updatableFiles as $filename => $content) {
+            file_put_contents($filename, $content);
+        }
 
         return Command::SUCCESS;
     }
@@ -246,6 +277,7 @@ private function scanValidators(string $directory): array
      * @param array<string> $denyList
      */
     private function addMethodToInterface(
+        PhpNamespace $namespace,
         string $originalName,
         InterfaceType $interfaceType,
         ReflectionClass $reflection,
@@ -287,12 +319,15 @@ private function addMethodToInterface(
         }
 
         foreach ($reflectionConstructor->getParameters() as $reflectionParameter) {
-            $this->addParameterToMethod($method, $reflectionParameter);
+            $this->addParameterToMethod($method, $reflectionParameter, $namespace);
         }
     }
 
-    private function addParameterToMethod(Method $method, ReflectionParameter $reflectionParameter): void
-    {
+    private function addParameterToMethod(
+        Method $method,
+        ReflectionParameter $reflectionParameter,
+        PhpNamespace $namespace,
+    ): void {
         if ($reflectionParameter->isVariadic()) {
             $method->setVariadic();
         }
@@ -303,6 +338,11 @@ private function addParameterToMethod(Method $method, ReflectionParameter $refle
         if ($type instanceof ReflectionUnionType) {
             foreach ($type->getTypes() as $subType) {
                 $types[] = $subType->getName();
+                if ($subType->isBuiltin()) {
+                    continue;
+                }
+
+                $namespace->addUse($subType->getName());
             }
         } elseif ($type instanceof ReflectionNamedType) {
             $types[] = $type->getName();
@@ -313,6 +353,10 @@ private function addParameterToMethod(Method $method, ReflectionParameter $refle
             ) {
                 return;
             }
+
+            if (!$type->isBuiltin()) {
+                $namespace->addUse($type->getName());
+            }
         }
 
         $parameter = $method->addParameter($reflectionParameter->getName());
@@ -342,25 +386,27 @@ private function addParameterToMethod(Method $method, ReflectionParameter $refle
         $parameter->setNullable(false);
     }
 
-    private function overwriteFile(string $content, string $basename): void
+    private function getFormattedContent(string $content, string $existingContent): string
     {
-        $srcDir = dirname(__DIR__, 2) . '/src';
-
-        $SPDX = ' * SPDX';
+        preg_match('/^<\?php\s*\/\*[\s\S]*?\*\//', $existingContent, $matches);
+        $existingHeader = $matches[0] ?? '';
+
+        $replacements = [
+            '/\n\n\t(public|\/\*\*)/m' => PHP_EOL . '    $1',
+            '/\t/m' => '    ',
+            '/\?([a-zA-Z]+) \$/' => '$1|null $',
+            '/\/\*\*\n +\* (.+)\n +\*\//m' => '/** $1 */',
+        ];
 
-        $finalContent = implode("\n\n", array_filter([
-            '<?php',
-            '/*',
-            $SPDX . '-License-Identifier: MIT',
-            $SPDX . '-FileCopyrightText: (c) Respect Project Contributors',
-            '/*',
+        return implode(PHP_EOL, [
+            trim($existingHeader) . PHP_EOL,
             'declare(strict_types=1);',
-            preg_replace('/extends (.+, )+/', 'extends' . "\n" . '\1', $content),
-        ]));
-
-        file_put_contents(
-            sprintf('%s/Mixins/%s.php', $srcDir, $basename),
-            $finalContent,
-        );
+            '',
+            preg_replace(
+                array_keys($replacements),
+                array_values($replacements),
+                $content,
+            ),
+        ]);
     }
 }