PhilDaiguille · PhilDaiguille · Apr 27, 2026 · Apr 27, 2026 · Apr 27, 2026
diff --git a/AGENTS.md b/AGENTS.md
diff --git a/README.md b/README.md
diff --git a/composer.json b/composer.json
diff --git a/src/Rules/AbstractA11yRule.php b/src/Rules/AbstractA11yRule.php
@@ -4,6 +4,8 @@
 
 namespace TwigA11y\Rules;
 
+use TwigA11y\Template\TemplateClassifier;
+use TwigA11y\Template\TemplateKind;
 use TwigCsFixer\Rules\AbstractRule;
 use TwigCsFixer\Token\Token;
 use TwigCsFixer\Token\Tokens;
@@ -12,8 +14,48 @@ abstract class AbstractA11yRule extends AbstractRule implements EvaluatableRuleI
 {
     use TokenCollectorTrait;
 
+    /** Cached decision for the currently-processed file when rules are reused */
+    private ?bool $skipThisFile = null;
+
+    // By default rules apply to all template kinds. Rules that should be
+    // limited to specific kinds can override supportedKinds().
+    /**
+     * @return TemplateKind[]
+     */
+    protected function supportedKinds(): array
+    {
+        return TemplateKind::cases();
+    }
+
+    // Rules can opt to run only once per file (for page-level scans).
+    protected function evaluateOncePerFile(): bool
+    {
+        return false;
+    }
+
     final protected function process(int $tokenIndex, Tokens $tokens): void
     {
+        // On the first token, determine the template kind and record whether
+        // this rule applies to the file. This supports rule instances being
+        // reused across multiple files.
+        if (0 === $tokenIndex) {
+            $kind = TemplateClassifier::classify(
+                $this->getFullContent($tokens)
+            );
+
+            $this->skipThisFile = !in_array($kind, $this->supportedKinds(), true);
+        }
+
+        // If earlier we decided this rule doesn't apply to this file, skip.
+        if (true === $this->skipThisFile) {
+            return;
+        }
+
+        // If the rule only runs once per file, only evaluate at tokenIndex 0.
+        if ($this->evaluateOncePerFile() && 0 !== $tokenIndex) {
+            return;
+        }
+
         $this->evaluate($tokens, $tokenIndex, $this->createEmitter());
     }
 

diff --git a/src/Rules/Structure/LandmarkRule.php b/src/Rules/Structure/LandmarkRule.php
@@ -5,6 +5,7 @@
 namespace TwigA11y\Rules\Structure;
 
 use TwigA11y\Rules\AbstractA11yRule;
+use TwigA11y\Template\TemplateKind;
 use TwigCsFixer\Token\Token;
 use TwigCsFixer\Token\Tokens;
 
@@ -25,13 +26,10 @@ public function evaluate(Tokens $tokens, int $tokenIndex, callable $emit): void
             return;
         }
 
-        // This rule is page-level. Only evaluate once per file (at tokenIndex 0)
-        // and only if the content looks like a full HTML page (contains
-        // a <body> or a <!DOCTYPE). This avoids flagging fragments/partials.
-        if (0 !== $tokenIndex) {
-            return;
-        }
-
+        // This is a page-level rule: only run once per file and only on full
+        // pages. The AbstractA11yRule helper provides the once-per-file
+        // behaviour; here we just need to check the full-page heuristics and
+        // emit if missing.
         $full = $this->getFullContent($tokens);
 
         // If this looks like a fragment (no body/doctype), skip evaluation
@@ -47,4 +45,17 @@ public function evaluate(Tokens $tokens, int $tokenIndex, callable $emit): void
         $first = $tokens->get(0);
         $emit('Page should include a main landmark', $first, 'Landmark.MissingMain');
     }
+
+    /**
+     * @return TemplateKind[]
+     */
+    protected function supportedKinds(): array
+    {
+        return [TemplateKind::FullPage];
+    }
+
+    protected function evaluateOncePerFile(): bool
+    {
+        return true;
+    }
 }
diff --git a/src/Rules/Structure/LangAttributeRule.php b/src/Rules/Structure/LangAttributeRule.php
@@ -5,6 +5,7 @@
 namespace TwigA11y\Rules\Structure;
 
 use TwigA11y\Rules\AbstractA11yRule;
+use TwigA11y\Template\TemplateKind;
 use TwigCsFixer\Token\Token;
 use TwigCsFixer\Token\Tokens;
 
@@ -29,4 +30,12 @@ public function evaluate(Tokens $tokens, int $tokenIndex, callable $emit): void
             $emit('The <html> element should have a lang attribute.', $token, 'LangAttribute.MissingLang');
         }
     }
+
+    /**
+     * @return TemplateKind[]
+     */
+    protected function supportedKinds(): array
+    {
+        return [TemplateKind::FullPage];
+    }
 }
diff --git a/src/Rules/Structure/MetaViewportRule.php b/src/Rules/Structure/MetaViewportRule.php
@@ -5,6 +5,7 @@
 namespace TwigA11y\Rules\Structure;
 
 use TwigA11y\Rules\AbstractA11yRule;
+use TwigA11y\Template\TemplateKind;
 use TwigCsFixer\Token\Token;
 use TwigCsFixer\Token\Tokens;
 
@@ -36,4 +37,17 @@ public function evaluate(Tokens $tokens, int $tokenIndex, callable $emit): void
             $emit('Avoid using user-scalable=no in the viewport meta.', $token, 'MetaViewport.UserScalable');
         }
     }
+
+    /**
+     * @return TemplateKind[]
+     */
+    protected function supportedKinds(): array
+    {
+        return [TemplateKind::FullPage];
+    }
+
+    protected function evaluateOncePerFile(): bool
+    {
+        return true;
+    }
 }
diff --git a/src/Rules/Structure/SkipLinkRule.php b/src/Rules/Structure/SkipLinkRule.php
@@ -5,6 +5,7 @@
 namespace TwigA11y\Rules\Structure;
 
 use TwigA11y\Rules\AbstractA11yRule;
+use TwigA11y\Template\TemplateKind;
 use TwigCsFixer\Token\Token;
 use TwigCsFixer\Token\Tokens;
 
@@ -18,13 +19,9 @@ public function evaluate(Tokens $tokens, int $tokenIndex, callable $emit): void
             return;
         }
 
-        // Page-level rule: only run once (tokenIndex 0) and only for full
-        // pages (containing <body> or <!DOCTYPE). This avoids reporting on
-        // partials/components.
-        if (0 !== $tokenIndex) {
-            return;
-        }
-
+        // Only perform the page-level checks once per file; AbstractA11yRule
+        // will enforce the evaluateOncePerFile behaviour if needed. Here we
+        // simply run the detection logic and emit on the current token.
         $content = $this->getFullContent($tokens);
 
         if (!str_contains($content, '<body') && !str_contains(strtoupper($content), '<!DOCTYPE')) {
@@ -39,6 +36,20 @@ public function evaluate(Tokens $tokens, int $tokenIndex, callable $emit): void
             return;
         }
 
-        $emit('Page should include a skip link to bypass navigation', $token, 'SkipLink.Missing');
+        $first = $tokens->get(0);
+        $emit('Page should include a skip link to bypass navigation', $first, 'SkipLink.Missing');
+    }
+
+    /**
+     * @return TemplateKind[]
+     */
+    protected function supportedKinds(): array
+    {
+        return [TemplateKind::FullPage];
+    }
+
+    protected function evaluateOncePerFile(): bool
+    {
+        return true;
     }
 }
diff --git a/src/Template/TemplateClassifier.php b/src/Template/TemplateClassifier.php
@@ -0,0 +1,39 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TwigA11y\Template;
+
+final class TemplateClassifier
+{
+    public static function classify(string $content): TemplateKind
+    {
+        $hasExtends = str_contains($content, '{% extends');
+        $hasBlock = str_contains($content, '{% block');
+        $hasHtml = false !== stripos($content, '<html');
+        $hasBody = false !== stripos($content, '<body');
+        $hasProps = str_contains($content, '{% props');
+
+        if ($hasProps) {
+            return TemplateKind::TwigUxComponent;
+        }
+
+        if ($hasExtends && $hasBlock) {
+            return TemplateKind::MixedTemplate;
+        }
+
+        if ($hasExtends) {
+            return TemplateKind::ChildTemplate;
+        }
+
+        if ($hasBlock && !$hasHtml) {
+            return TemplateKind::ParentTemplate;
+        }
+
+        if ($hasHtml && $hasBody) {
+            return TemplateKind::FullPage;
+        }
+
+        return TemplateKind::Partial;
+    }
+}
diff --git a/src/Template/TemplateKind.php b/src/Template/TemplateKind.php
@@ -0,0 +1,15 @@
+<?php
+
+declare(strict_types=1);
+
+namespace TwigA11y\Template;
+
+enum TemplateKind
+{
+    case FullPage;
+    case ChildTemplate;
+    case Partial;
+    case ParentTemplate;
+    case MixedTemplate;
+    case TwigUxComponent;
+}
diff --git a/tests/Rules/Structure/MetaViewportRuleTest.php b/tests/Rules/Structure/MetaViewportRuleTest.php
@@ -23,7 +23,9 @@ public function testRule(string $fixture, array $expectedErrors): void
     /** @return iterable<string, array{0:string,1:array<null|string>}> */
     public static function provideFixtures(): iterable
     {
-        yield 'bad viewport' => [__DIR__.'/Fixtures/invalid/meta_viewport_bad.html.twig', ['MetaViewport.MetaViewport.UserScalable:1:1' => 'Avoid using user-scalable=no in the viewport meta.']];
+        // This fixture is a fragment (no <html>/<body>) — rule is page-level
+        // and should not emit on partials.
+        yield 'bad viewport' => [__DIR__.'/Fixtures/invalid/meta_viewport_bad.html.twig', []];
 
         yield 'ok' => [__DIR__.'/Fixtures/valid/no_banned.html.twig', []];
     }
@@ -33,6 +35,7 @@ public function testRuleWorksWhenTheSameInstanceIsReusedAcrossFiles(): void
         $rule = new MetaViewportRule();
 
         $this->checkRule($rule, [], __DIR__.'/Fixtures/valid/no_banned.html.twig');
-        $this->checkRule($rule, ['MetaViewport.MetaViewport.UserScalable:1:1' => 'Avoid using user-scalable=no in the viewport meta.'], __DIR__.'/Fixtures/invalid/meta_viewport_bad.html.twig');
+        // fragment should still not trigger when same instance is reused
+        $this->checkRule($rule, [], __DIR__.'/Fixtures/invalid/meta_viewport_bad.html.twig');
     }
 }