Add doc linter to check outdated templates

henriquemoody · henriquemoody · commit bb3be233e548 · 2026-01-13T22:32:39.000-07:00
We don't often change the tempaltes of validators, but when we do it's
extremely important that the documentation of the validators match the
exact template the validator has.
diff --git a/bin/console b/bin/console
@@ -20,6 +20,7 @@ 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 Respect\Dev\Markdown\Linters\ValidatorTemplatesLinter;
 use SebastianBergmann\Diff\Differ;
 use SebastianBergmann\Diff\Output\UnifiedDiffOutputBuilder;
 use Symfony\Component\Console\Application;
@@ -33,6 +34,7 @@ return (static function () {
         new ValidatorHeaderLinter(),
         new ValidatorIndexLinter(),
         new ValidatorRelatedLinter(),
+        new ValidatorTemplatesLinter(),
     )));
     $application->addCommand(new UpdateDomainSuffixesCommand());
     $application->addCommand(new UpdateDomainToplevelCommand());
diff --git a/composer.json b/composer.json
@@ -75,6 +75,7 @@
         "docs:validators:headers": "bin/console docs:validators:headers",
         "docs:validators:index": "bin/console docs:validators:index",
         "docs:validators:related": "bin/console docs:validators:related",
+        "docs:validators:templates": "bin/console docs:validators:templates",
         "docheader": "vendor/bin/docheader check library/ tests/",
         "phpcs": "vendor/bin/phpcs",
         "phpstan": "vendor/bin/phpstan analyze",
@@ -83,7 +84,8 @@
         "docs": [
             "@docs:validators:headers",
             "@docs:validators:index",
-            "@docs:validators:related"
+            "@docs:validators:related",
+            "@docs:validators:templates"
         ],
         "qa": [
             "@docheader",
diff --git a/docs/validators/All.md b/docs/validators/All.md
@@ -24,7 +24,9 @@ This validator uses [Length](Length.md) with [GreaterThan][GreaterThan.md] inter
 | `default`  | Every item in |
 | `inverted` | Every item in |
 
-This template serve as message prefixes.:
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
 
 ```php
 v::all(v::floatType())->assert([1.5, 2]);
diff --git a/docs/validators/DateTimeDiff.md b/docs/validators/DateTimeDiff.md
@@ -31,16 +31,6 @@ The supported types are:
 
 ## Templates
 
-The first two templates serve as message suffixes:
-
-```php
-v::dateTimeDiff('years', v::equals(2))->assert('1 year ago')
-// The number of years between now and 1 year ago must be equal to 2
-
-v::not(v::dateTimeDiff('years', v::lessThan(8)))->assert('7 year ago')
-// The number of years between now and 7 year ago must not be less than 8
-```
-
 ### `DateTimeDiff::TEMPLATE_STANDARD`
 
 Used when `$format` and `$now` are not defined.
@@ -54,10 +44,17 @@ Used when `$format` and `$now` are not defined.
 
 Used when `$format` or `$now` are defined.
 
-| Mode       | Template                                                       |
-| ---------- | -------------------------------------------------------------- |
-| `default`  | The number of {{type&#124;trans}} between {{now&#124;raw}} and |
-| `inverted` | The number of {{type&#124;trans}} between {{now&#124;raw}} and |
+| Mode       | Template                                              |
+| ---------- | ----------------------------------------------------- |
+| `default`  | The number of {{type&#124;trans}} between {{now}} and |
+| `inverted` | The number of {{type&#124;trans}} between {{now}} and |
+
+### `DateTimeDiff::TEMPLATE_NOT_A_DATE`
+
+| Mode       | Template                                                                       |
+| ---------- | ------------------------------------------------------------------------------ |
+| `default`  | For comparison with {{now&#124;raw}}, {{subject}} must be a valid datetime     |
+| `inverted` | For comparison with {{now&#124;raw}}, {{subject}} must not be a valid datetime |
 
 ### `DateTimeDiff::TEMPLATE_WRONG_FORMAT`
 
@@ -68,6 +65,18 @@ Used when the input cannot be parsed with the given format.
 | `default`  | For comparison with {{now&#124;raw}}, {{subject}} must be a valid datetime in the format {{sample&#124;raw}}     |
 | `inverted` | For comparison with {{now&#124;raw}}, {{subject}} must not be a valid datetime in the format {{sample&#124;raw}} |
 
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
+
+```php
+v::dateTimeDiff('years', v::equals(2))->assert('1 year ago')
+// The number of years between now and 1 year ago must be equal to 2
+
+v::not(v::dateTimeDiff('years', v::lessThan(8)))->assert('7 year ago')
+// The number of years between now and 7 year ago must not be less than 8
+```
+
 ## Template placeholders
 
 | Placeholder | Description                                                      |
diff --git a/docs/validators/Instance.md b/docs/validators/Instance.md
@@ -17,8 +17,8 @@ Message template for this validator includes `{{instanceName}}`.
 
 | Mode       | Template                                                    |
 | ---------- | ----------------------------------------------------------- |
-| `default`  | {{subject}} must be an instance of `{{class&#124;raw}}`     |
-| `inverted` | {{subject}} must not be an instance of `{{class&#124;raw}}` |
+| `default`  | {{subject}} must be an instance of {{class&#124;quote}}     |
+| `inverted` | {{subject}} must not be an instance of {{class&#124;quote}} |
 
 ## Template placeholders
 
diff --git a/docs/validators/Length.md b/docs/validators/Length.md
@@ -31,7 +31,16 @@ Used when it's possible to get the length of the input.
 | `default`  | The length of |
 | `inverted` | The length of |
 
-This template serve as message prefixes.:
+### `Length::TEMPLATE_WRONG_TYPE`
+
+| Mode       | Template                                              |
+| ---------- | ----------------------------------------------------- |
+| `default`  | {{subject}} must be a countable value or a string     |
+| `inverted` | {{subject}} must not be a countable value or a string |
+
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
 
 ```php
 v::length(v::equals(3))->assert('tulip');
diff --git a/docs/validators/Max.md b/docs/validators/Max.md
@@ -28,6 +28,10 @@ This validator uses [Length](Length.md) with [GreaterThan][GreaterThan.md] inter
 | `default`  | The maximum of |
 | `inverted` | The maximum of |
 
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
+
 ## Template placeholders
 
 | Placeholder | Description                                                      |
diff --git a/docs/validators/Min.md b/docs/validators/Min.md
@@ -28,6 +28,10 @@ This validator uses [Length](Length.md) with [GreaterThan][GreaterThan.md] inter
 | `default`  | The minimum of |
 | `inverted` | The minimum of |
 
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
+
 ## Template placeholders
 
 | Placeholder | Description                                                      |
diff --git a/docs/validators/NullOr.md b/docs/validators/NullOr.md
@@ -31,7 +31,9 @@ v::nullOrBetween(1, 3)->isValid(null); // true
 | `default`  | or must be null      |
 | `inverted` | and must not be null |
 
-The templates from this validator serve as message suffixes:
+## Template as suffix
+
+The template serves as a suffix to the template of the inner validator.
 
 ```php
 v::nullOr(v::alpha())->assert('has1number');
diff --git a/docs/validators/Regex.md b/docs/validators/Regex.md
@@ -16,8 +16,8 @@ Message template for this validator includes `{{regex}}`.
 
 | Mode       | Template                                                    |
 | ---------- | ----------------------------------------------------------- |
-| `default`  | {{subject}} must match the pattern `{{regex&#124;raw}}`     |
-| `inverted` | {{subject}} must not match the pattern `{{regex&#124;raw}}` |
+| `default`  | {{subject}} must match the pattern {{regex&#124;quote}}     |
+| `inverted` | {{subject}} must not match the pattern {{regex&#124;quote}} |
 
 ## Template placeholders
 
diff --git a/docs/validators/Size.md b/docs/validators/Size.md
@@ -28,16 +28,6 @@ This validator will accept:
 | `default`  | The size in {{unit&#124;trans}} of |
 | `inverted` | The size in {{unit&#124;trans}} of |
 
-This template serve as message prefix:
-
-```php
-v::size('MB', v::equals(2))->assert('filename.txt')
-// Message: The size in megabytes of "filename.txt" must be equal to 2
-
-v::size('KB', v::not(v::equals(56)))->assert('filename.txt')
-// Message: The size in kilobytes of "filename.txt" must not be equal to 56
-```
-
 ### `Size::TEMPLATE_WRONG_TYPE`
 
 Used when the input is not a valid file path, a `SplFileInfo` object, or a PSR-7 interface.
@@ -47,6 +37,18 @@ Used when the input is not a valid file path, a `SplFileInfo` object, or a PSR-7
 | `default`  | {{subject}} must be a filename or an instance of SplFileInfo or a PSR-7 interface     |
 | `inverted` | {{subject}} must not be a filename or an instance of SplFileInfo or a PSR-7 interface |
 
+## Template as prefix
+
+The template serves as a prefix to the template of the inner validator.
+
+```php
+v::size('MB', v::equals(2))->assert('filename.txt')
+// Message: The size in megabytes of "filename.txt" must be equal to 2
+
+v::size('KB', v::not(v::equals(56)))->assert('filename.txt')
+// Message: The size in kilobytes of "filename.txt" must not be equal to 56
+```
+
 ## Template placeholders
 
 | Placeholder | Description                                                      |
diff --git a/docs/validators/UndefOr.md b/docs/validators/UndefOr.md
@@ -34,7 +34,9 @@ v::undefOrBetween(1, 3)->isValid(2); // true
 | `default`  | or must be undefined      |
 | `inverted` | and must not be undefined |
 
-The templates from this validator serve as message suffixes:
+## Template as suffix
+
+The template serves as a suffix to the template of the inner validator.
 
 ```php
 v::undefOr(v::alpha())->assert('has1number');
diff --git a/src-dev/Markdown/Linters/ValidatorTemplatesLinter.php b/src-dev/Markdown/Linters/ValidatorTemplatesLinter.php
@@ -0,0 +1,94 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Respect\Dev\Markdown\Linters;
+
+use ReflectionClass;
+use Respect\Dev\Markdown\Content;
+use Respect\Dev\Markdown\File;
+use Respect\Dev\Markdown\Linter;
+use Respect\Validation\Message\Template;
+use UnexpectedValueException;
+
+use function array_find_key;
+use function basename;
+use function preg_match;
+use function preg_replace;
+use function sprintf;
+use function str_contains;
+use function str_starts_with;
+
+final readonly class ValidatorTemplatesLinter implements Linter
+{
+    public function lint(File $file): File
+    {
+        if (!str_contains($file->filename, '/validators/') || str_contains($file->filename, '/validators/index.md')) {
+            return $file;
+        }
+
+        $validator = basename($file->filename, '.md');
+        $templates = $this->getTemplates($validator);
+
+        if ($templates === []) {
+            return $file;
+        }
+
+        $descriptions = [];
+        try {
+            $currentTemplates = $file->content->getSection('## Templates');
+            $templateLines = $currentTemplates->toArray();
+            foreach ($templateLines as $index => $currentLine) {
+                if (!str_starts_with($currentLine, '### ')) {
+                    continue;
+                }
+
+                $id = preg_replace('/^### `.+::([A-Z_]+)`/', '$1', $currentLine);
+                if (!isset($templateLines[$index + 2]) || !preg_match('/^[A-Z]/', $templateLines[$index + 2])) {
+                    continue;
+                }
+
+                $descriptions[$id] = $templateLines[$index + 2];
+            }
+        } catch (UnexpectedValueException) {
+            // No existing Templates section, that's fine
+        }
+
+        $content = new Content();
+        $content->h2('Templates');
+        foreach ($templates as $id => $template) {
+            $content->h3(sprintf('`%s::%s`', $validator, $id));
+            if (isset($descriptions[$id])) {
+                $content->paragraph($descriptions[$id]);
+                $content->emptyLine();
+            }
+
+            $content->table(['Mode', 'Template'], [
+                ['`default`', $template->default],
+                ['`inverted`', $template->inverted],
+            ]);
+        }
+
+        return $file->withContent($file->content->withSection($content));
+    }
+
+    /** @return array<string, Template> */
+    private function getTemplates(string $validator): array
+    {
+        $reflectionClass = new ReflectionClass('Respect\\Validation\\Validators\\' . $validator);
+        $constants = $reflectionClass->getConstants();
+
+        $templates = [];
+        foreach ($reflectionClass->getAttributes(Template::class) as $attribute) {
+            $template = $attribute->newInstance();
+            $id = array_find_key($constants, static fn($constant) => $template->id === $constant);
+            if ($id === null) {
+                continue;
+            }
+
+            $templates[$id] = $template;
+        }
+
+        return $templates;
+    }
+}
