Add GitHub action to check related validators

This commit ensures that if validator A has a direct link to validator
B, validator B will have a direct link to validator A too.

We are already doing that, but this commit will add a GitHub action
with a command that will fail if there are any changes required.

Author: henriquemoody

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

@@ -34,3 +34,6 @@ jobs:
 
       - name: Validator headers
         run: bin/console docs:validators:headers
+
+      - name: Related validators
+        run: bin/console docs:validators:related

bin/console

@@ -13,6 +13,7 @@ require __DIR__ . '/../vendor/autoload.php';
 use Respect\Dev\Commands\CreateMixinCommand;
 use Respect\Dev\Commands\DocsValidatorsHeadersCommand;
 use Respect\Dev\Commands\DocsValidatorsListCommand;
+use Respect\Dev\Commands\DocsValidatorsRelatedCommand;
 use Respect\Dev\Commands\UpdateDomainSuffixesCommand;
 use Respect\Dev\Commands\UpdateDomainToplevelCommand;
 use Respect\Dev\Commands\UpdatePostalCodesCommand;
@@ -28,6 +29,7 @@ return (static function () {
     $application->addCommand(new CreateMixinCommand());
     $application->addCommand(new DocsValidatorsHeadersCommand($differ));
     $application->addCommand(new DocsValidatorsListCommand($differ));
+    $application->addCommand(new DocsValidatorsRelatedCommand($differ));
     $application->addCommand(new UpdateDomainSuffixesCommand());
     $application->addCommand(new UpdateDomainToplevelCommand());
     $application->addCommand(new UpdatePostalCodesCommand());

composer.json

@@ -74,14 +74,16 @@
     "scripts": {
         "docs:validators:headers": "bin/console docs:validators:headers",
         "docs:validators:index": "bin/console docs:validators:index",
+        "docs:validators:related": "bin/console docs:validators:related",
         "docheader": "vendor/bin/docheader check library/ tests/",
         "phpcs": "vendor/bin/phpcs",
         "phpstan": "vendor/bin/phpstan analyze",
         "phpunit": "vendor/bin/phpunit --testsuite=unit",
         "pest": "vendor/bin/pest --testsuite=feature --compact",
         "docs": [
             "@docs:validators:headers",
-            "@docs:validators:index"
+            "@docs:validators:index",
+            "@docs:validators:related"
         ],
         "qa": [
             "@docheader",

docs/validators/IterableVal.md

@@ -13,7 +13,7 @@ v::iterableVal()->isValid('string'); // false
 
 ## Note
 
-This validator doesn't behave as PHP's [is_iterable() function because it considers that you can iterate over any object.
+This validator doesn't behave as PHP's [is_iterable()][] function because it considers that you can iterate over any object.
 
 ## Templates
 

src-dev/Commands/DocsValidatorsRelatedCommand.php

@@ -0,0 +1,139 @@
+<?php
+
+/*
+ * Copyright (c) Alexandre Gomes Gaigalas <alganet@gmail.com>
+ * SPDX-License-Identifier: MIT
+ */
+
+declare(strict_types=1);
+
+namespace Respect\Dev\Commands;
+
+use Respect\Dev\Markdown\Builder;
+use Respect\Dev\Markdown\Differ;
+use Symfony\Component\Console\Attribute\AsCommand;
+use Symfony\Component\Console\Command\Command;
+use Symfony\Component\Console\Input\InputInterface;
+use Symfony\Component\Console\Output\OutputInterface;
+use Symfony\Component\Finder\Finder;
+
+use function array_keys;
+use function array_unique;
+use function count;
+use function dirname;
+use function file_get_contents;
+use function implode;
+use function in_array;
+use function preg_match_all;
+use function preg_split;
+use function sort;
+use function sprintf;
+use function str_contains;
+
+use const PHP_EOL;
+
+#[AsCommand(
+    name: 'docs:validators:related',
+    description: 'Update the list of related validators of each validator documentation file',
+)]
+final class DocsValidatorsRelatedCommand extends Command
+{
+    public function __construct(
+        private readonly Differ $differ,
+    ) {
+        parent::__construct();
+    }
+
+    protected function execute(InputInterface $input, OutputInterface $output): int
+    {
+        $diffs = [];
+        foreach ($this->getAllRelatedValidators() as $validator => $relatedValidators) {
+            $diff = $this->updateMarkdown($validator, $relatedValidators);
+            if ($diff === null) {
+                continue;
+            }
+
+            $diffs[] = $diff;
+        }
+
+        if ($diffs === []) {
+            $output->writeln('<info>No changes needed.</info>');
+
+            return Command::SUCCESS;
+        }
+
+        $output->writeln(sprintf('<comment>Changed needed in %d files.</comment>', count($diffs)));
+        $output->writeln(implode(PHP_EOL, $diffs));
+
+        return Command::FAILURE;
+    }
+
+    /** @param array<string, array<string>> $relatedValidators */
+    private function updateMarkdown(string $validator, array $relatedValidators): string|null
+    {
+        $builder = Builder::fromDocs(sprintf('validators/%s.md', $validator));
+
+        // Extract links at the bottom
+        preg_match_all('/^\[.+\]: .+$/m', $builder->existingContent, $linkMatches);
+        $references = implode(PHP_EOL, $linkMatches[0] ?? []);
+
+        // Get content before "See also" or "---"
+        $sections = preg_split('/(^## See also:|^---)/m', $builder->existingContent);
+
+        $builder->raw($sections[0] ?? $builder->existingContent);
+        $builder->hr();
+        $builder->paragraph('See also:');
+        $builder->newLine();
+        foreach ($relatedValidators as $relatedValidator) {
+            $builder->anchorListItem($relatedValidator, $relatedValidator . '.md');
+        }
+
+        $builder->newLine();
+        $builder->raw($references);
+
+        $diff = $this->differ->diff($builder);
+        if ($diff !== null) {
+            $builder->save();
+        }
+
+        return $diff;
+    }
+
+    /** @return array<string, array<string>> */
+    private function getAllRelatedValidators(): array
+    {
+        $docsDirectory = dirname(__DIR__, 2) . '/docs';
+
+        $finder = new Finder();
+        $finder->in(dirname(__DIR__, 2) . '/library/Validators')->depth(0)->files()->name('*.php')->sortByName();
+
+        $allRelatedValidators = [];
+        foreach ($finder as $file) {
+            $validator = $file->getBasename('.php');
+            $filename = sprintf('%s/validators/%s.md', $docsDirectory, $validator);
+            $content = file_get_contents($filename);
+            if ($content === false) {
+                continue;
+            }
+
+            $relatedValidators = [];
+
+            preg_match_all('/\[([^\]]+)\]\(([^\)]+\.md)\)/', $content, $matches);
+            foreach (array_keys($matches[0]) as $key) {
+                $related = $matches[1][$key];
+                $document = $matches[2][$key];
+                if (str_contains($document, '/') || in_array($related, $relatedValidators)) {
+                    continue;
+                }
+
+                $relatedValidators[] = $related;
+            }
+
+            $allRelatedValidators[$validator] = array_unique($relatedValidators);
+
+            sort($allRelatedValidators[$validator]);
+        }
+
+        return $allRelatedValidators;
+    }
+}