feat: add VideoTrackRule to enforce track kind="captions" on <video> (WCAG 1.2.2) with tests

Author: PhilDaiguille

src/Rules/Media/VideoTrackRule.php

@@ -0,0 +1,48 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TwigA11y\Rules\Media;
+
+use TwigA11y\Rules\AbstractA11yRule;
+use TwigCsFixer\Token\Tokens;
+
+final class VideoTrackRule extends AbstractA11yRule
+{
+    protected function process(int $tokenIndex, Tokens $tokens): void
+    {
+        // Only run once per file
+        if (0 !== $tokenIndex) {
+            return;
+        }
+
+        $full = '';
+        foreach ($tokens->toArray() as $t) {
+            $full .= $t->getValue();
+        }
+
+        if (!str_contains($full, '<video')) {
+            return;
+        }
+
+        // Find all <video ...>...</video> blocks
+        if (!preg_match_all('/<video\b([^>]*)>(.*?)<\/video>/is', $full, $m, PREG_SET_ORDER)) {
+            return;
+        }
+
+        foreach ($m as $set) {
+            $openAttrs = $set[1];
+            $content = $set[2];
+
+            // If a <track kind="captions" exists inside the video block, OK
+            if (preg_match('/<track\b[^>]*\bkind\s*=\s*(?:"|\')captions(?:"|\')/i', $content)) {
+                continue;
+            }
+
+            // No captions found — report error at token 0 for determinism
+            $token = $tokens->get(0);
+            $this->addError('Video should have captions (track kind="captions").', $token, 'VideoTrack.MissingCaptions');
+            return;
+        }
+    }
+}

tests/Rules/Media/Fixtures/invalid/video_no_captions.html.twig

@@ -0,0 +1,3 @@
+<video controls>
+    <source src="movie.mp4" type="video/mp4">
+</video>

tests/Rules/Media/Fixtures/valid/video_with_captions.html.twig

@@ -0,0 +1,4 @@
+<video controls>
+    <source src="movie.mp4" type="video/mp4">
+    <track kind="captions" srclang="en" label="English captions" src="captions_en.vtt">
+</video>

tests/Rules/Media/VideoTrackRuleTest.php

@@ -0,0 +1,31 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TwigA11y\Tests\Rules\Media;
+
+use PHPUnit\Framework\Attributes\CoversNothing;
+use PHPUnit\Framework\Attributes\DataProvider;
+use TwigA11y\Rules\Media\VideoTrackRule;
+use TwigCsFixer\Test\AbstractRuleTestCase;
+
+#[CoversNothing]
+/** @internal */
+final class VideoTrackRuleTest extends AbstractRuleTestCase
+{
+    #[DataProvider('provideFixtures')]
+    public function testRule(string $fixture, array $expectedErrors): void
+    {
+        $this->checkRule(new VideoTrackRule(), $expectedErrors, $fixture);
+    }
+
+    public static function provideFixtures(): iterable
+    {
+        yield 'video with captions' => [__DIR__.'/Fixtures/valid/video_with_captions.html.twig', []];
+
+        yield 'video without captions' => [
+            __DIR__.'/Fixtures/invalid/video_no_captions.html.twig',
+            ['VideoTrack.VideoTrack.MissingCaptions:1:1' => 'Video should have captions (track kind="captions").'],
+        ];
+    }
+}