Add doc linter 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.

Author: henriquemoody

bin/console

@@ -19,6 +19,7 @@ use Respect\Dev\Markdown\CompositeLinter;
 use Respect\Dev\Markdown\Differ as MarkdownDiffer;
 use Respect\Dev\Markdown\Linters\ValidatorHeaderLinter;
 use Respect\Dev\Markdown\Linters\ValidatorIndexLinter;
+use Respect\Dev\Markdown\Linters\ValidatorRelatedLinter;
 use SebastianBergmann\Diff\Differ;
 use SebastianBergmann\Diff\Output\UnifiedDiffOutputBuilder;
 use Symfony\Component\Console\Application;
@@ -29,8 +30,9 @@ return (static function () {
     $application = new Application('Respect/Validation', '3.0');
     $application->addCommand(new CreateMixinCommand());
     $application->addCommand(new DocsLinterCommand($differ, new CompositeLinter(
-        new ValidatorIndexLinter(),
         new ValidatorHeaderLinter(),
+        new ValidatorIndexLinter(),
+        new ValidatorRelatedLinter(),
     )));
     $application->addCommand(new UpdateDomainSuffixesCommand());
     $application->addCommand(new UpdateDomainToplevelCommand());

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/Markdown/Linters/ValidatorRelatedLinter.php

@@ -0,0 +1,78 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\Dev\Markdown\Linters;
+
+use Respect\Dev\Markdown\Content;
+use Respect\Dev\Markdown\File;
+use Respect\Dev\Markdown\Linter;
+
+use function array_keys;
+use function array_unique;
+use function basename;
+use function dirname;
+use function file_get_contents;
+use function in_array;
+use function preg_match_all;
+use function sort;
+use function sprintf;
+use function str_contains;
+use function str_ends_with;
+
+final readonly class ValidatorRelatedLinter implements Linter
+{
+    public function lint(File $file): File
+    {
+        if (!str_contains($file->filename, '/validators/') || str_ends_with($file->filename, '/validators/index.md')) {
+            return $file;
+        }
+
+        $validator = basename($file->filename, '.md');
+        $relatedValidators = $this->getRelatedValidators($validator);
+
+        if ($relatedValidators === []) {
+            return $file;
+        }
+
+        $content = new Content();
+        $content->paragraph('See also:');
+        $content->emptyLine();
+        foreach ($relatedValidators as $relatedValidator) {
+            $content->anchorListItem($relatedValidator, $relatedValidator . '.md');
+        }
+
+        $content->emptyLine();
+
+        return $file->withContent($file->content->withSection($content));
+    }
+
+    /** @return array<string> */
+    private function getRelatedValidators(string $validator): array
+    {
+        $docsDirectory = dirname(__DIR__, 3) . '/docs';
+        $filename = sprintf('%s/validators/%s.md', $docsDirectory, $validator);
+        $content = file_get_contents($filename);
+        if ($content === false) {
+            return [];
+        }
+
+        $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;
+        }
+
+        $relatedValidators = array_unique($relatedValidators);
+        sort($relatedValidators);
+
+        return $relatedValidators;
+    }
+}