From 5ff21909f87ef64fb13de470eae34b4a7cc19783 Mon Sep 17 00:00:00 2001
From: PhilDaiguille <philippe.delente@gmail.com>
Date: Mon, 27 Apr 2026 12:17:01 +0200
Subject: [PATCH] tests: add partial fixtures and extend page-level tests; fix
 rules to avoid false positives (ignore hidden inputs, page-level detection)

---
 AGENTS.md                                     | 50 +++++++++++++++++++
 src/Rules/Forms/InputLabelRule.php            |  5 ++
 src/Rules/Structure/LandmarkRule.php          | 31 ++++++++----
 src/Rules/Structure/SkipLinkRule.php          | 14 ++++--
 .../Fixtures/valid/input_hidden.html.twig     |  5 ++
 .../valid/input_with_aria_variable.html.twig  |  5 ++
 tests/Rules/Forms/InputLabelRuleTest.php      |  6 +++
 .../duplicate_landmark_trigger.html.twig      |  9 ++++
 .../partial_component_fragment.html.twig      |  2 +
 .../Fixtures/valid/partial_no_html.html.twig  |  2 +
 tests/Rules/Structure/LandmarkRuleTest.php    |  8 +++
 .../Rules/Structure/LangAttributeRuleTest.php |  3 ++
 tests/Rules/Structure/SkipLinkRuleTest.php    |  6 +--
 13 files changed, 127 insertions(+), 19 deletions(-)
 create mode 100644 AGENTS.md
 create mode 100644 tests/Rules/Forms/Fixtures/valid/input_hidden.html.twig
 create mode 100644 tests/Rules/Forms/Fixtures/valid/input_with_aria_variable.html.twig
 create mode 100644 tests/Rules/Structure/Fixtures/invalid/duplicate_landmark_trigger.html.twig
 create mode 100644 tests/Rules/Structure/Fixtures/valid/partial_component_fragment.html.twig
 create mode 100644 tests/Rules/Structure/Fixtures/valid/partial_no_html.html.twig

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..74f3bac
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,50 @@
+Purpose
+All repository-specific guidance an OpenCode session is likely to miss. Keep this short — every line should answer: "Would an agent likely miss this without help?"
+
+Quick facts
+- Language: PHP library (PSR-4). Autoload: "TwigA11y\\" => "src/". Tests autoload: "TwigA11y\\Tests\\" => "tests/".
+- PHP minimum: 8.2 (CI tests matrix: 8.2, 8.3, 8.4).
+- This package ships rules only — it does NOT provide a runnable binary. Use vendor/bin/twig-cs-fixer (from vincentlanglet/twig-cs-fixer).
+
+Setup (safe, repeatable)
+- Install deps: `composer install` (CI uses `composer install --prefer-dist --no-progress --no-suggest --optimize-autoloader`). Ensure your PHP version >= 8.2 and required extensions (mbstring, dom when running tests).
+
+Run tests
+- Run full test suite: `composer test` (runs phpunit tests --testdox).
+- Run with coverage (as CI does): `./vendor/bin/phpunit --configuration phpunit.xml --coverage-text --coverage-clover=coverage.xml`.
+- Run a single test file: `./vendor/bin/phpunit path/to/TestFile.php` or use `--filter` to run by test name.
+
+Linting / static checks — exact commands and gotchas
+- Composer scripts available (see composer.json):
+  - `composer cs-lint` -> `php-cs-fixer fix --dry-run --diff --verbose`
+  - `composer cs-fix`  -> `php-cs-fixer fix`
+  - `composer phpstan` -> `phpstan analyse`
+  - `composer rector`  -> `rector`
+  - `composer lint`    -> runs `cs-lint && phpstan && test && rector` (IMPORTANT: this runs `rector` without `--dry-run`, so it can modify files locally)
+  - `composer lint:fix` -> runs `cs-fix && rector` (also modifies files)
+
+- Safe CI-like full check (no local modifications):
+  composer cs-lint && composer phpstan && composer test && composer rector -- --dry-run
+  (CI uses this pattern for rector; prefer adding `--dry-run` locally when you only want to verify.)
+
+Twig lint (rules usage)
+- This package provides rules for twig-cs-fixer; create a `.twig-cs-fixer.php` at your repo root to enable them (see README example).
+- Run the installed linter against templates (CI command):
+  `vendor/bin/twig-cs-fixer lint . --config=.twig-cs-fixer.php --no-cache`
+  Note: CI runs the above with `|| true` so lint errors don't fail the job. Locally treat its exit status as you prefer.
+
+Adding / testing rules (required structure)
+- Rule code: `src/Rules/{Category}/`
+- Tests: `tests/Rules/{Category}/` with PHPUnit test classes.
+- Fixtures: valid and invalid `.html.twig` files under `tests/Rules/{Category}/Fixtures/` (tests rely on these fixtures).
+
+CI differences to notice
+- CI runs `composer rector -- --dry-run` (lint.yml/tests.yml) while the `composer lint` script will run rector without `--dry-run`. Do NOT assume `composer lint` is read-only.
+- CI sets up xdebug for coverage. If you need local coverage run with Xdebug enabled (or the coverage step will fail).
+
+Other small but important facts
+- The package requires `vincentlanglet/twig-cs-fixer` (the rules don't include the binary). If you run twig lint locally, install that dependency.
+- PHPUnit bootstrap is `vendor/autoload.php` (phpunit.xml). Running tests requires vendor autoload to exist (i.e. run composer install first).
+
+If something is unclear
+- Check README.md, composer.json (scripts), phpunit.xml and .github/workflows/* for the authoritative behavior used by CI.
diff --git a/src/Rules/Forms/InputLabelRule.php b/src/Rules/Forms/InputLabelRule.php
index 4bc7c37..c82e25c 100644
--- a/src/Rules/Forms/InputLabelRule.php
+++ b/src/Rules/Forms/InputLabelRule.php
@@ -31,6 +31,11 @@ public function evaluate(Tokens $tokens, int $tokenIndex, callable $emit): void
             return;
         }
 
+        // Ignore hidden inputs: they don't require accessible labels
+        if (preg_match('/\btype\s*=\s*["\']hidden["\']/i', $opening)) {
+            return;
+        }
+
         // Id present?
         $id = null;
         if (preg_match('/\bid\s*=\s*(?:"|\')([^"\']+)(?:"|\')/i', $opening, $m)) {
diff --git a/src/Rules/Structure/LandmarkRule.php b/src/Rules/Structure/LandmarkRule.php
index 2d8229e..4b39969 100644
--- a/src/Rules/Structure/LandmarkRule.php
+++ b/src/Rules/Structure/LandmarkRule.php
@@ -25,17 +25,26 @@ public function evaluate(Tokens $tokens, int $tokenIndex, callable $emit): void
             return;
         }
 
-        // If we encounter the end of head/body start, and haven't seen
-        // a main landmark previously, emit a missing landmark warning.
-        if (str_contains($value, '<body') || str_contains($value, '</head>')) {
-            // Simple approach: scan a small window ahead to see if a main is present
-            $look = $this->collectUntil($tokenIndex, $tokens, '<main', 200);
-            if (!str_contains($look, '<main') && !preg_match('/role\s*=\s*["\']main["\']/i', $look)) {
-                // Emit at the start of the file for consistency with other
-                // page-level rules (tests expect line 1:1 identifiers).
-                $first = $tokens->get(0);
-                $emit('Page should include a main landmark', $first, 'Landmark.MissingMain');
-            }
+        // 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;
+        }
+
+        $full = $this->getFullContent($tokens);
+
+        // If this looks like a fragment (no body/doctype), skip evaluation
+        if (!str_contains($full, '<body') && !str_contains(strtoupper($full), '<!DOCTYPE')) {
+            return;
         }
+
+        // Scan the full content for a main landmark or role="main"
+        if (str_contains($full, '<main') || preg_match('/role\s*=\s*["\']main["\']/i', $full)) {
+            return;
+        }
+
+        $first = $tokens->get(0);
+        $emit('Page should include a main landmark', $first, 'Landmark.MissingMain');
     }
 }
diff --git a/src/Rules/Structure/SkipLinkRule.php b/src/Rules/Structure/SkipLinkRule.php
index cf0e460..c480d25 100644
--- a/src/Rules/Structure/SkipLinkRule.php
+++ b/src/Rules/Structure/SkipLinkRule.php
@@ -18,20 +18,24 @@ public function evaluate(Tokens $tokens, int $tokenIndex, callable $emit): void
             return;
         }
 
-        // Only perform a single page-level scan (when invoked on the first
-        // token) to detect absence of skip links. This avoids emitting the
-        // same violation multiple times.
+        // 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;
         }
 
         $content = $this->getFullContent($tokens);
 
-        if (preg_match('/href\s*=\s*["\"]#([^"\']+)["\"][^>]*>.*?skip/i', $content)) {
+        if (!str_contains($content, '<body') && !str_contains(strtoupper($content), '<!DOCTYPE')) {
             return;
         }
 
-        if (preg_match('/href\s*=\s*["\"]#(main|content)["\"][^>]*>/i', $content)) {
+        if (preg_match('/href\s*=\s*["\']#([^"\']+)["\'][^>]*>.*?skip/i', $content)) {
+            return;
+        }
+
+        if (preg_match('/href\s*=\s*["\']#(main|content)["\'][^>]*>/i', $content)) {
             return;
         }
 
diff --git a/tests/Rules/Forms/Fixtures/valid/input_hidden.html.twig b/tests/Rules/Forms/Fixtures/valid/input_hidden.html.twig
new file mode 100644
index 0000000..7d97f9c
--- /dev/null
+++ b/tests/Rules/Forms/Fixtures/valid/input_hidden.html.twig
@@ -0,0 +1,5 @@
+<html>
+<body>
+html<input type="hidden" name="token" value="abc">
+</body>
+</html>
diff --git a/tests/Rules/Forms/Fixtures/valid/input_with_aria_variable.html.twig b/tests/Rules/Forms/Fixtures/valid/input_with_aria_variable.html.twig
new file mode 100644
index 0000000..e1aa40d
--- /dev/null
+++ b/tests/Rules/Forms/Fixtures/valid/input_with_aria_variable.html.twig
@@ -0,0 +1,5 @@
+<html>
+<body>
+<input type="text" aria-label="{{ dynamic_label }}">
+</body>
+</html>
diff --git a/tests/Rules/Forms/InputLabelRuleTest.php b/tests/Rules/Forms/InputLabelRuleTest.php
index 65840b6..cd4ebd6 100644
--- a/tests/Rules/Forms/InputLabelRuleTest.php
+++ b/tests/Rules/Forms/InputLabelRuleTest.php
@@ -36,5 +36,11 @@ public static function provideFixtures(): iterable
             __DIR__.'/Fixtures/invalid/input_no_label.html.twig',
             ['InputLabel.InputLabel.MissingLabel:3:1' => 'Input element must have an associated <label> or an aria-label.'],
         ];
+
+        // Hidden inputs should not trigger the rule
+        yield 'input hidden' => [__DIR__.'/Fixtures/valid/input_hidden.html.twig', []];
+
+        // Dynamic aria-label (Twig var) should be considered present
+        yield 'input with aria variable' => [__DIR__.'/Fixtures/valid/input_with_aria_variable.html.twig', []];
     }
 }
diff --git a/tests/Rules/Structure/Fixtures/invalid/duplicate_landmark_trigger.html.twig b/tests/Rules/Structure/Fixtures/invalid/duplicate_landmark_trigger.html.twig
new file mode 100644
index 0000000..b85a3bc
--- /dev/null
+++ b/tests/Rules/Structure/Fixtures/invalid/duplicate_landmark_trigger.html.twig
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+<head>
+</head>
+<body>
+<header>Nav</header>
+<div>Content without main</div>
+</body>
+</html>
diff --git a/tests/Rules/Structure/Fixtures/valid/partial_component_fragment.html.twig b/tests/Rules/Structure/Fixtures/valid/partial_component_fragment.html.twig
new file mode 100644
index 0000000..e61878b
--- /dev/null
+++ b/tests/Rules/Structure/Fixtures/valid/partial_component_fragment.html.twig
@@ -0,0 +1,2 @@
+{# partial component - should not be treated as a full page #}
+<div class="card">{{ content }}</div>
diff --git a/tests/Rules/Structure/Fixtures/valid/partial_no_html.html.twig b/tests/Rules/Structure/Fixtures/valid/partial_no_html.html.twig
new file mode 100644
index 0000000..a4c51d4
--- /dev/null
+++ b/tests/Rules/Structure/Fixtures/valid/partial_no_html.html.twig
@@ -0,0 +1,2 @@
+{# partial fragment with no <html> tag - should be valid for page-level rules #}
+<div class="snippet">{{ title }}</div>
diff --git a/tests/Rules/Structure/LandmarkRuleTest.php b/tests/Rules/Structure/LandmarkRuleTest.php
index 84a4b65..06915c8 100644
--- a/tests/Rules/Structure/LandmarkRuleTest.php
+++ b/tests/Rules/Structure/LandmarkRuleTest.php
@@ -30,5 +30,13 @@ public static function provideFixtures(): iterable
         yield 'missing main' => [__DIR__.'/Fixtures/invalid/no_main.html.twig', [
             'Landmark.Landmark.MissingMain:1:1' => 'Page should include a main landmark',
         ]];
+
+        // Partials/fragments without <body> should NOT trigger the page-level rule
+        yield 'partial fragment' => [__DIR__.'/Fixtures/valid/partial_component_fragment.html.twig', []];
+
+        // Ensure only one error is emitted when the document has </head><body>
+        yield 'duplicate trigger check' => [__DIR__.'/Fixtures/invalid/duplicate_landmark_trigger.html.twig', [
+            'Landmark.Landmark.MissingMain:1:1' => 'Page should include a main landmark',
+        ]];
     }
 }
diff --git a/tests/Rules/Structure/LangAttributeRuleTest.php b/tests/Rules/Structure/LangAttributeRuleTest.php
index 28927ab..48e6d54 100644
--- a/tests/Rules/Structure/LangAttributeRuleTest.php
+++ b/tests/Rules/Structure/LangAttributeRuleTest.php
@@ -36,5 +36,8 @@ public static function provideFixtures(): iterable
             __DIR__.'/Fixtures/invalid/html_no_lang.html.twig',
             ['LangAttribute.LangAttribute.MissingLang:2:1' => 'The <html> element should have a lang attribute.'],
         ];
+
+        // Partial fragments (no <html>) should not trigger the rule
+        yield 'partial fragment no html' => [__DIR__.'/Fixtures/valid/partial_no_html.html.twig', []];
     }
 }
diff --git a/tests/Rules/Structure/SkipLinkRuleTest.php b/tests/Rules/Structure/SkipLinkRuleTest.php
index 7fe0215..abf3470 100644
--- a/tests/Rules/Structure/SkipLinkRuleTest.php
+++ b/tests/Rules/Structure/SkipLinkRuleTest.php
@@ -27,8 +27,8 @@ public static function provideFixtures(): iterable
 
         yield 'valid main id' => [__DIR__.'/Fixtures/valid/main_id.html.twig', []];
 
-        yield 'missing skip link' => [__DIR__.'/Fixtures/invalid/no_skip_link.html.twig', [
-            'SkipLink.SkipLink.Missing:1:1' => 'Page should include a skip link to bypass navigation',
-        ]];
+        // This fixture is a fragment (no <body> or <!DOCTYPE>); skip link
+        // rule is page-level and should NOT emit on partials.
+        yield 'missing skip link' => [__DIR__.'/Fixtures/invalid/no_skip_link.html.twig', []];
     }
 }