From 90f59d66659ed815b8f61975f0701c73bb09ba64 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Sat, 8 Aug 2026 15:27:48 +0200 Subject: [PATCH 1/3] fix(gate-38): a mount point is not a page root, and the remedy it demanded regressed a11y (#214, #216, #227) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit WCAG 2.4.1 is a property of a DOCUMENT. gate-38 was asking it of two shapes that own no document, and reporting all of them. templates/**/*.php Nextcloud's Template renderer SUBSTITUTES an app template into core's page. Measured across the fleet: all 30 app templates are fragments, NOT ONE emits , or . The typical body is literally `
`. 8 templates across 6 apps failed this way. AdminRoot.vue rendered INTO core's Settings page, inside the section core already built. A is a stack of s, not an app shell (#227). In both cases the only way to close the finding was to add a SECOND "skip to content" anchor, pointing into the middle of a page that already has one and announced to every screen-reader user ahead of core's real one — a WCAG 2.4.1 regression demanded by a WCAG 2.4.1 gate. WHAT STILL FAILS - src/App.vue / src/views/App.vue with a bespoke shell - **/*Root.vue that is not a settings surface - a PHP template that DOES own the document and has no bypass mechanism. This WIDENS the PHP arm: it used to look only at templates/settings/, and now asks every app template the question. The classifier is scripts/lib/php_template_scope.py, not a grep, and that is load-bearing. The first cut WAS a grep, and the first fixture it met defeated it: the fixture's own explanatory comment contained ``, so a bare mount point classified as a page root and the fix silently did nothing. Same defect as gate-64 — a checker that greps a string literal misses every constant and matches every comment, failing both ways at once. Classification now runs on emitted markup with PHP regions and HTML comments removed, and both comment shapes are pinned in test_php_template_scope.py. The same trap bit the FIXTURE twice: the AdminRoot.vue fixture's comment spelled out the wrapper element it does not have, the gate matched the COMMENT and accepted the file, and the "#227 is fixed" assertion passed IDENTICALLY with the fix reverted. Caught by mutation-checking, not by reading. All three mutations now go red: * classifier forced to "owns document" -> fragment assertions fail * settings-surface exclusion removed -> #227 assertion fails * PHP arm removed -> the standalone.php TP is lost Tests: 4 new fixtures (a document-owning template with and without a bypass anchor; a mount point; a settings surface), 4 new assertions in test_gate_monitoring_and_skiplink.sh (16/16 green), and a new 15-case test_php_template_scope.py. The "not reported" assertions run in the `accidental/` tree, where the gate is demonstrably firing in the same run, so an absence is a decision and never an empty scope. A missing helper now reports SKIP-wiring, not PASS (#147): without the classifier every template reads as a fragment and the whole PHP arm would evaporate into a green. Refs #214, #216, #227 --- hydra-gates/scripts/lib/php_template_scope.py | 97 ++++++++++++ .../lib/test_gate_monitoring_and_skiplink.sh | 33 ++++ .../scripts/lib/test_php_template_scope.py | 149 ++++++++++++++++++ hydra-gates/scripts/run-hydra-gates.sh | 130 ++++++++++++--- .../src/views/settings/AdminRoot.vue | 38 +++++ .../accidental/templates/settings/admin.php | 17 ++ .../accidental/templates/standalone.php | 28 ++++ .../stated/templates/standalone.php | 24 +++ 8 files changed, 497 insertions(+), 19 deletions(-) create mode 100644 hydra-gates/scripts/lib/php_template_scope.py create mode 100644 hydra-gates/scripts/lib/test_php_template_scope.py create mode 100644 hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/src/views/settings/AdminRoot.vue create mode 100644 hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/templates/settings/admin.php create mode 100644 hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/templates/standalone.php create mode 100644 hydra-gates/scripts/test-fixtures/monitoring-skiplink/stated/templates/standalone.php diff --git a/hydra-gates/scripts/lib/php_template_scope.py b/hydra-gates/scripts/lib/php_template_scope.py new file mode 100644 index 000000000..607283d22 --- /dev/null +++ b/hydra-gates/scripts/lib/php_template_scope.py @@ -0,0 +1,97 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: EUPL-1.2 +"""Does a Nextcloud PHP template OWN THE DOCUMENT, or is it a fragment? + +WHY THIS EXISTS +--------------- +Nextcloud's `OCP\\Template` renderer SUBSTITUTES an app template into core's +own page. A template that emits no `` / `` is a fragment inside a +document core already built — core emitted that page's landmarks, its `lang` +attribute and its skip link long before the template's first byte. + +gate-38 was asking every `templates/settings/*.php` in the fleet for a skip +link. Measured: NOT ONE of the 30 app templates in this fleet owns a document +— the typical body is literally `
`, a Vue +mount point — so the finding was universal and its only remedy was to inject +a SECOND "skip to content" anchor ahead of core's real one. A WCAG 2.4.1 +regression demanded by a WCAG 2.4.1 gate (#214, #216, #227). + +WHY A HELPER AND NOT A GREP +--------------------------- +The first cut of this check was `grep -iE '<(html|body)\\b'`, and the very +first fixture it ran against defeated it: the fixture's own explanatory +comment contained the words ``, so a bare mount point was classified as +a page root. That is the gate-64 defect verbatim — a checker that greps a +string literal misses every constant and matches every comment, failing both +ways at once — so the classification is done on EMITTED MARKUP only: + + * `` regions are removed. Anything inside them is code, a + docblock or a `//` comment; none of it is markup the browser receives. + * `` HTML comments are removed. Commented-out markup ships + nothing. + +Usage: + php_template_scope.py --owns-document # exit 0 = owns, 1 = fragment + php_template_scope.py --classify ... # ": page-root|fragment" +""" +from __future__ import annotations + +import re +import sys + +# `` and the short echo form ``. An unterminated opener runs +# to end of file, which is the language's own rule and the common shape of a +# template whose PHP header is followed by nothing but more PHP. +PHP_BLOCK = re.compile(r'<\?(?:php\b|=)?.*?(?:\?>|\Z)', re.DOTALL | re.IGNORECASE) +HTML_COMMENT = re.compile(r'', re.DOTALL) + +DOCUMENT_TAG = re.compile(r'<(?:html|body)\b', re.IGNORECASE) + + +def emitted_markup(src: str) -> str: + """The template's output shape: PHP regions and HTML comments removed. + + Order matters. Comments are stripped AFTER php blocks, because a `?>` + inside an HTML comment really does close the block in PHP, and pretending + otherwise would swallow markup that does ship. + """ + return HTML_COMMENT.sub(' ', PHP_BLOCK.sub(' ', src)) + + +def owns_document(src: str) -> bool: + """True when the template emits `` or `` itself. + + Only such a template is rendered outside core's shell, and only such a + template can carry a bypass mechanism (SC 2.4.1) or a `lang` attribute + (SC 3.1.1) of its own. + """ + return bool(DOCUMENT_TAG.search(emitted_markup(src))) + + +def _read(path: str) -> str: + with open(path, encoding='utf-8', errors='replace') as f: + return f.read() + + +def main(argv: list[str]) -> int: + if len(argv) >= 3 and argv[1] == '--owns-document': + try: + return 0 if owns_document(_read(argv[2])) else 1 + except OSError: + # Unreadable is NOT "fragment". Refuse rather than answer. + print(f'php_template_scope: cannot read {argv[2]}', file=sys.stderr) + return 2 + if len(argv) >= 3 and argv[1] == '--classify': + for path in argv[2:]: + try: + kind = 'page-root' if owns_document(_read(path)) else 'fragment' + except OSError: + kind = 'unreadable' + print(f'{path}: {kind}') + return 0 + print(__doc__, file=sys.stderr) + return 2 + + +if __name__ == '__main__': + sys.exit(main(sys.argv)) diff --git a/hydra-gates/scripts/lib/test_gate_monitoring_and_skiplink.sh b/hydra-gates/scripts/lib/test_gate_monitoring_and_skiplink.sh index b4bc8d5c9..830e79f7c 100755 --- a/hydra-gates/scripts/lib/test_gate_monitoring_and_skiplink.sh +++ b/hydra-gates/scripts/lib/test_gate_monitoring_and_skiplink.sh @@ -113,6 +113,11 @@ if _run "${FIXTURES}/accidental"; then _expect_gate 38 FAIL "accidental: a bespoke shell with no skip link is still reported" _expect_log "${_SLLOG}" 'App\.vue: no shell' \ "accidental: gate-38 names the root component" + # #214/#216 — the PHP half must keep a true positive. `standalone.php` + # emits and : it owns the document, so SC 2.4.1 is its to + # satisfy, and it does not. + _expect_log "${_SLLOG}" 'templates/standalone\.php: no shell' \ + "accidental: a PHP template that OWNS the document and has no bypass link is still reported" fi # --------------------------------------------------------------------------- @@ -128,6 +133,34 @@ if _run "${FIXTURES}/stated"; then _expect_gate 38 PASS "stated: a CnAppRoot shell counts as having NC's skip link" _expect_not_log "${_SLLOG}" 'App\.vue' \ "stated: gate-38 log is empty" + _expect_not_log "${_SLLOG}" 'standalone\.php' \ + "stated: a document-owning template WITH a bypass anchor is not a finding" +fi + +# --------------------------------------------------------------------------- +# 3. MOUNT POINT vs PAGE ROOT (#214 / #216 / #227). +# +# These three assertions run against `accidental/` — the fixture where +# EVERYTHING ELSE fails. That is deliberate: asserting "not reported" in a +# tree where the gate reports nothing proves nothing at all. Here the gate +# is demonstrably firing (section 1 named App.vue and standalone.php in +# this same run), so an absence is a decision rather than an empty scope. +# --------------------------------------------------------------------------- +if _run "${FIXTURES}/accidental"; then + _expect_log "${_SLLOG}" 'App\.vue|standalone\.php' \ + "mount-point control: gate-38 IS firing in this tree (positive control for the three below)" + _expect_not_log "${_SLLOG}" 'settings/admin\.php' \ + "#214/#216: a fragment template (
mount point) is not a page root" + _expect_not_log "${_SLLOG}" 'AdminRoot\.vue' \ + "#227: an admin-settings surface cannot own a page shell, so it is not asked for one" + # And the narrowing must not have swallowed the whole PHP arm: exactly one + # template is named, and it is the document-owning one. + if [ "$(printf '%s\n' "${_SLLOG}" | grep -c '\.php:')" = "1" ]; then + _ok "#214/#216: exactly ONE of the two PHP templates is in scope — the one that owns the document" + else + _bad "#214/#216: expected exactly 1 .php finding, got $(printf '%s\n' "${_SLLOG}" | grep -c '\.php:')" + printf '%s\n' "${_SLLOG}" | sed 's/^/ /' + fi fi echo diff --git a/hydra-gates/scripts/lib/test_php_template_scope.py b/hydra-gates/scripts/lib/test_php_template_scope.py new file mode 100644 index 000000000..15bc22acb --- /dev/null +++ b/hydra-gates/scripts/lib/test_php_template_scope.py @@ -0,0 +1,149 @@ +#!/usr/bin/env python3 +# SPDX-License-Identifier: EUPL-1.2 +"""Tests for php_template_scope (gate-38's page-root / fragment classifier). + + python3 scripts/lib/test_php_template_scope.py + +WHY EACH CASE IS HERE +--------------------- +gate-38's PHP arm reported 8 templates across 6 apps, and every one was a +fragment whose page — and whose skip link — belongs to Nextcloud core. The +narrowing that removes those findings is the single question "does this file +emit a document?", so this suite is where that question is held honest. + +The comment cases are not hypothetical padding. The FIRST implementation was +`grep -iE '<(html|body)\\b'`, and the first fixture it met defeated it: the +fixture's own explanatory comment said ``, so a bare mount point +classified as a page root and the whole fix silently did nothing. Both +comment shapes are pinned below. +""" +from __future__ import annotations + +import os +import sys +import unittest + +sys.path.insert(0, os.path.dirname(os.path.abspath(__file__))) +import php_template_scope as pts # noqa: E402 + + +class Fragments(unittest.TestCase): + """Everything here is rendered INTO a page core already built.""" + + def test_the_fleet_mount_point(self): + # procest/templates/settings/admin.php, verbatim shape. This is the + # single most common template in the fleet. + self.assertFalse(pts.owns_document( + "\n" + '
\n')) + + def test_a_long_fragment_with_real_markup_is_still_a_fragment(self): + # nldesign/templates/settings/admin.php is 502 lines of real controls + # and still owns no document. + self.assertFalse(pts.owns_document( + '
\n' + '

NL Design System Theme

\n' + ' \n' + ' \n' + '
\n')) + + def test_a_php_comment_naming_html_does_not_make_it_a_page_root(self): + # THE REGRESSION THAT MOTIVATED THIS HELPER. A `//` comment inside a + # PHP block explaining that core emitted the element must not + # be read as this file emitting one. + self.assertFalse(pts.owns_document( + " and long before this\n" + "// file's first byte; this template is only a mount point.\n" + "?>\n" + '
\n')) + + def test_a_docblock_naming_body_does_not_make_it_a_page_root(self): + self.assertFalse(pts.owns_document( + ".\n */\n?>\n" + '
\n')) + + def test_commented_out_markup_ships_nothing(self): + self.assertFalse(pts.owns_document( + '\n' + '
\n')) + + def test_an_all_php_file_owns_no_document(self): + self.assertFalse(pts.owns_document(" 1];\n")) + + def test_empty_file(self): + self.assertFalse(pts.owns_document('')) + + +class PageRoots(unittest.TestCase): + """A template that emits the document is in scope and must stay in scope. + + If these ever go false the gate has stopped asking anyone the question, + and gate-38's PHP arm is decoration. + """ + + def test_a_standalone_document(self): + self.assertTrue(pts.owns_document( + '\n\nx\n' + '
\n\n')) + + def test_body_alone_is_enough(self): + # Some standalone templates are included after a partial header. + self.assertTrue(pts.owns_document('\n

hi

\n')) + + def test_markup_after_a_closed_php_block_is_still_seen(self): + # The PHP-stripper must not eat the rest of the file. A `?>` closes + # exactly one block. + self.assertTrue(pts.owns_document( + "\nhi\n")) + + def test_html_between_two_php_blocks(self): + self.assertTrue(pts.owns_document( + "\n\n\n" + "hi\n")) + + def test_uppercase_tags(self): + self.assertTrue(pts.owns_document('hi')) + + def test_a_real_comment_next_to_a_real_document(self): + # Stripping comments must not strip the document with them. + self.assertTrue(pts.owns_document( + '\n' + '

hi

\n')) + + +class UnterminatedPhp(unittest.TestCase): + def test_an_unclosed_php_opener_swallows_the_rest(self): + # PHP's own rule, and the common shape of a pure-logic template. + self.assertFalse(pts.owns_document(" mentioned here\n$x = 1;\n")) + + +class Cli(unittest.TestCase): + """The bash caller keys on the EXIT STATUS, so the status is a contract. + + Gate-19 returned a finding COUNT as an exit status and lost 256 findings + to a byte; an exit status this gate reads must be tested as an interface, + not assumed. + """ + + def _write(self, tmp, name, content): + p = os.path.join(tmp, name) + with open(p, 'w', encoding='utf-8') as f: + f.write(content) + return p + + def test_exit_codes(self): + import tempfile + with tempfile.TemporaryDirectory() as tmp: + root = self._write(tmp, 'root.php', 'hi') + frag = self._write(tmp, 'frag.php', '
') + self.assertEqual(pts.main(['x', '--owns-document', root]), 0) + self.assertEqual(pts.main(['x', '--owns-document', frag]), 1) + # A file that cannot be read is NOT silently "fragment" — that + # would drop it from scope and read as a pass. + self.assertEqual( + pts.main(['x', '--owns-document', os.path.join(tmp, 'nope.php')]), 2) + + +if __name__ == '__main__': + unittest.main(verbosity=2) diff --git a/hydra-gates/scripts/run-hydra-gates.sh b/hydra-gates/scripts/run-hydra-gates.sh index 24e7b9eea..201e9a142 100755 --- a/hydra-gates/scripts/run-hydra-gates.sh +++ b/hydra-gates/scripts/run-hydra-gates.sh @@ -3121,24 +3121,90 @@ fi # --------------------------------------------------------------------------- -# Gate 38: Skip-link — every app entry-point Vue (App.vue / *Root.vue) or -# admin/settings PHP template must include a skip-to-content affordance, -# either via NC's shell (typically inherited by mounting under ) -# or via an explicit `` / `` link as -# the first focusable element. Per WCAG 2.2 AA SC 2.4.1 (Bypass Blocks). -# -# Heuristic: a file is in scope if it's a top-level Vue mount root (App.vue -# / **/AdminRoot.vue / **/Root.vue) OR a settings admin template -# (templates/settings/*.php). We pass if the file either renders -# `` / `` (which inherits NC's skip-link) OR -# contains a literal `skip-` link / `skip-to-content` reference. +# Gate 38: Skip-link — every app PAGE ROOT must include a skip-to-content +# affordance, either via NC's shell (typically inherited by mounting under +# ) or via an explicit `` / `` +# link as the first focusable element. Per WCAG 2.2 AA SC 2.4.1 (Bypass +# Blocks). +# +# A PAGE ROOT IS NOT A MOUNT POINT (#214 / #216 / #227) +# ---------------------------------------------------- +# SC 2.4.1 is a property of a DOCUMENT: "a mechanism is available to bypass +# blocks of content repeated on multiple WEB PAGES". Only the thing that owns +# the document can satisfy it. Two shapes in this fleet own no document, and +# this gate was reporting all of them: +# +# templates/**/*.php Nextcloud's `Template` renderer SUBSTITUTES an app +# template into core's own page. Every one of the 30 +# PHP templates in this fleet is a fragment — measured: +# NOT ONE emits , or . The typical +# body is literally `
`, +# a Vue mount point. The skip link for that page is +# emitted by NC core, above this file's first byte. +# 8 templates across 6 apps failed this way. +# +# Admin / personal `AdminRoot.vue` is rendered INTO core's Settings +# settings roots page, inside the section core already built. It is a +# — a stack of +# s — not an app shell. #227: these +# surfaces cannot own a page shell, so they cannot own +# a skip link either. +# +# In both cases the gate's implied remedy was to ADD a skip link to an element +# that is not the page root: a second "skip to content" anchor pointing into +# the middle of a page that already has one, announced to every screen-reader +# user ahead of core's real one. A WCAG 2.4.1 REGRESSION demanded by a WCAG +# 2.4.1 gate, which is why the finding could not be closed honestly. +# +# WHAT REMAINS IN SCOPE, AND STILL FAILS +# -------------------------------------- +# - src/App.vue, src/views/App.vue — the app's own shell +# - **/*Root.vue that is NOT a settings surface +# - a PHP template that DOES own the document, i.e. emits / +# (a standalone / PublicPage template rendered outside core's shell). No +# fleet app has one today; the gate is ready for the first that does, and +# the fixture pair in scripts/test-fixtures/monitoring-skiplink proves it +# still fires. Note this WIDENS the PHP arm: it used to look only at +# templates/settings/, and now asks every app template the question. # # References: # - openspec/architecture/wcag-coverage.md SC 2.4.1 +# - ConductionNL/.github#214, #216, #227 # --------------------------------------------------------------------------- -if [ -d src ] || [ -d templates ]; then +if [ -d src ] || [ -d templates ] || [ -d appinfo/templates ]; then _sl_log=${HYDRA_GATE_LOG_DIR}/hydra-gate-skip-link.log : > "${_sl_log}" + # A Vue root that is a SETTINGS SURFACE, not a page root. Two independent + # signals, because neither alone covers the fleet: + # name — all 8 settings roots measured across the fleet are called + # AdminRoot.vue / PersonalRoot.vue / AdminSettings.vue, and 3 of + # them (petstore, portaliq, openregister) are NOT under a + # settings/ path, so a path rule alone would miss them. + # shell — a root rendering / / + # is a stack of settings sections mounted + # into core's Settings page, whatever it happens to be called. + _sl_is_settings_surface() { + local _f="$1" + case "${_f##*/}" in + AdminRoot.vue|PersonalRoot.vue|AdminSettings.vue|PersonalSettings.vue) return 0 ;; + esac + case "${_f}" in + */views/settings/*|*/views/admin/*|*/components/userSettings/*) return 0 ;; + esac + grep -qE '/dev/null + } + # A PHP template owns the document only if it EMITS one. + # + # This is deliberately NOT a grep. The first cut of it was, and the very + # first fixture defeated it: that fixture's own explanatory COMMENT + # contained the word ``, so a bare `
` mount point + # classified as a page root. That is the gate-64 defect verbatim — a + # checker that greps a string literal misses every constant and matches + # every comment, failing both ways at once. scripts/lib/php_template_scope.py + # classifies EMITTED MARKUP, with PHP regions and HTML comments removed. + _sl_php_owns_document() { + python3 "${SCRIPT_DIR}/lib/php_template_scope.py" --owns-document "$1" 2>/dev/null + } _sl_check() { local _f="$1" _in_scope "$_f" || return 0 @@ -3172,19 +3238,45 @@ if [ -d src ] || [ -d templates ]; then done while IFS= read -r _f; do [ -z "$_f" ] && continue + # #227: a settings surface is not a page root and cannot own a skip + # link. Skipping it is the only honest verdict — the alternative + # remedy regresses the page that already has one. + _sl_is_settings_surface "$_f" && continue _sl_check "$_f" done < <(_enum_tracked 'Root\.vue$' src) - if [ -d templates/settings ]; then + # #214 / #216: a PHP template is checked only when it owns the document. + # `templates/settings/` is no longer the scope — the question asked of + # EVERY app template is whether it emits /. + _sl_ran=1 + if [ -d templates ] || [ -d appinfo/templates ]; then + _sl_helper="${SCRIPT_DIR}/lib/php_template_scope.py" + _sl_php=() while IFS= read -r _f; do [ -z "$_f" ] && continue - _sl_check "$_f" - done < <(find templates/settings -name '*.php' 2>/dev/null) + _in_scope "$_f" && _sl_php+=("$_f") + done < <(find templates appinfo/templates -name '*.php' 2>/dev/null) + if [ "${#_sl_php[@]}" -eq 0 ]; then + : # nothing in scope; the verdict below describes the diff, as everywhere else. + elif [ ! -f "${_sl_helper}" ]; then + # A MISSING HELPER MUST NOT REPORT PASS (#147). Without the + # classifier every template silently reads as a fragment, the + # whole PHP arm evaporates, and the gate goes green on nothing. + _sl_ran=0 + _skip 38 "skip-link" wiring "php_template_scope.py not found at ${_sl_helper} — ${#_sl_php[@]} PHP template(s) were in scope and NONE were classified; a document-owning template with no bypass mechanism (WCAG 2.4.1) is UNVERIFIED by this run." + else + for _f in "${_sl_php[@]}"; do + _sl_php_owns_document "$_f" || continue + _sl_check "$_f" + done + fi fi _sl_fail=$(wc -l < "${_sl_log}" 2>/dev/null || echo 0) - if [ "${_sl_fail}" -eq 0 ]; then - _pass 38 "skip-link" - else - _fail 38 "skip-link" "${_sl_fail} root component(s) without skip-link / — see ${_sl_log}" + if [ "${_sl_ran}" -eq 1 ]; then + if [ "${_sl_fail}" -eq 0 ]; then + _pass 38 "skip-link" + else + _fail 38 "skip-link" "${_sl_fail} page root(s) without skip-link / — see ${_sl_log}" + fi fi fi diff --git a/hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/src/views/settings/AdminRoot.vue b/hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/src/views/settings/AdminRoot.vue new file mode 100644 index 000000000..83fcce516 --- /dev/null +++ b/hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/src/views/settings/AdminRoot.vue @@ -0,0 +1,38 @@ + + + + diff --git a/hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/templates/settings/admin.php b/hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/templates/settings/admin.php new file mode 100644 index 000000000..6d98f2ee8 --- /dev/null +++ b/hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/templates/settings/admin.php @@ -0,0 +1,17 @@ +, its landmarks and its bypass mechanism long before this +// file's first byte. +// +// It owns no document, so it cannot own a skip link, and adding one here +// would announce a second "skip to content" ahead of core's real one. +// gate-38 must NOT report it. Its sibling `standalone.php` differs by owning +// the document, and must still be reported. +script('fixture', 'admin'); +style('fixture', 'admin'); +?> +
diff --git a/hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/templates/standalone.php b/hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/templates/standalone.php new file mode 100644 index 000000000..847dc482c --- /dev/null +++ b/hydra-gates/scripts/test-fixtures/monitoring-skiplink/accidental/templates/standalone.php @@ -0,0 +1,28 @@ + and itself, so it +// is rendered outside Nextcloud's shell and nothing above it emitted a +// bypass mechanism. It has no jump-to-content affordance. It is a genuine +// WCAG 2.4.1 failure and MUST be reported. +// +// Its sibling `settings/admin.php` differs by exactly the one thing the +// #214/#216 narrowing accepts — it is a fragment — and must NOT be reported. +?> + + + + + Fixture standalone page + + +
+
+ +
+ + diff --git a/hydra-gates/scripts/test-fixtures/monitoring-skiplink/stated/templates/standalone.php b/hydra-gates/scripts/test-fixtures/monitoring-skiplink/stated/templates/standalone.php new file mode 100644 index 000000000..d38e31f88 --- /dev/null +++ b/hydra-gates/scripts/test-fixtures/monitoring-skiplink/stated/templates/standalone.php @@ -0,0 +1,24 @@ + + + + + + Fixture standalone page + + + + +
+ +
+ + From a9f51da1869237476677fe7d6d181444189fa385 Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Sat, 8 Aug 2026 15:52:40 +0200 Subject: [PATCH 2/3] =?UTF-8?q?fix(gate-38):=20answer=20from=20stdout,=20n?= =?UTF-8?q?ot=20the=20exit=20byte=20=E2=80=94=20and=20survive=20gate-19's?= =?UTF-8?q?=20leaked=20`set=20-e`?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adopts the gate-19 / #249 signalling convention, and fixes two ways the PHP arm could have gone falsely green. 1. THE EXIT BYTE WAS THE ANSWER, AND A CRASH SHARES ITS VALUE. `--owns-document` returned 0=owns / 1=fragment. A helper that CRASHES also exits 1. Every template would have classified as a fragment, the whole PHP arm would have evaporated, and gate-38 would have reported PASS having inspected nothing. The answer now comes from STDOUT — one `--classify` call for the whole set, printing `: page-root|fragment` — and a non-zero exit is a wiring failure, reported as SKIPPED with stderr KEPT rather than discarded. Also one python process instead of one per template. 2. A LATENT BUG IN main(), found by the assertion above. gate-19's block (line ~1901) turns `set -e` ON and leaves it on for every gate after it, though this script's header sets only `set -u`. The first run of the crash test did not report a falsely-green gate — it reported NO GATE AT ALL: the non-zero helper killed the entire runner mid-sweep, 21 later gates silently unreported, and the run ended on the abort guard. The call is now wrapped in `set +e` with the caller's flag restored. Tests: 2 new wiring assertions (classifier MISSING -> SKIPPED; classifier CRASHING -> SKIPPED), 18/18 green. The crash assertion is the one that found the `set -e` leak; without it that failure mode is invisible, because an aborted run's PASS lines read exactly like a clean run's. Merged origin/main rather than rebasing: the branch is shared and the fleet force-push guard is right to refuse a history rewrite. --- .../lib/test_gate_monitoring_and_skiplink.sh | 44 +++++++++++++++++++ hydra-gates/scripts/run-hydra-gates.sh | 41 ++++++++++++++--- 2 files changed, 78 insertions(+), 7 deletions(-) diff --git a/hydra-gates/scripts/lib/test_gate_monitoring_and_skiplink.sh b/hydra-gates/scripts/lib/test_gate_monitoring_and_skiplink.sh index 830e79f7c..7848751cd 100755 --- a/hydra-gates/scripts/lib/test_gate_monitoring_and_skiplink.sh +++ b/hydra-gates/scripts/lib/test_gate_monitoring_and_skiplink.sh @@ -163,6 +163,50 @@ if _run "${FIXTURES}/accidental"; then fi fi +# --------------------------------------------------------------------------- +# 4. A BROKEN CLASSIFIER MUST NOT REPORT PASS (#147 / #249). +# +# gate-38's PHP arm is driven entirely by php_template_scope.py. If that +# helper crashes and the runner reads its exit byte as an answer, every +# template classifies as "fragment", the whole arm evaporates, and the gate +# reports PASS having inspected nothing — a falsely-green gate manufactured +# by its own plumbing. Both wiring failures are asserted here. +# --------------------------------------------------------------------------- +_broken="$(mktemp -d "${TMPDIR:-/tmp}/hydra-gate-broken.XXXXXXXX")" +cp -r "${PKG_ROOT}" "${_broken}/pkg" 2>/dev/null +_BROKEN_RUNNER="${_broken}/pkg/scripts/run-hydra-gates.sh" + +_expect_skip() { # + local _out _logdir + _logdir="$(mktemp -d "${TMPDIR:-/tmp}/hydra-gate-test.XXXXXXXX")" + _out="$(HYDRA_GATE_LOG_DIR="${_logdir}" bash "$1" "${FIXTURES}/stated" 2>&1 || true)" + local _line + _line="$(printf '%s' "${_out}" | grep -E '^\[gate-38\] ' | head -1)" + case "${_line}" in + *"SKIPPED"*) _ok "$2 — ${_line%%—*}" ;; + *": PASS"*) _bad "$2 — reported PASS having classified NOTHING: ${_line}" ;; + *) _bad "$2 — wanted SKIPPED, got: ${_line:-}" ;; + esac +} + +if [ -f "${_BROKEN_RUNNER}" ]; then + # 4a. helper absent + mv "${_broken}/pkg/scripts/lib/php_template_scope.py" \ + "${_broken}/pkg/scripts/lib/php_template_scope.py.hidden" + _expect_skip "${_BROKEN_RUNNER}" "a MISSING classifier reports SKIPPED, not PASS (#147)" + mv "${_broken}/pkg/scripts/lib/php_template_scope.py.hidden" \ + "${_broken}/pkg/scripts/lib/php_template_scope.py" + # 4b. helper present but crashing. This is the case an exit-byte boolean + # could not tell from "fragment": a crash exits 1, and so does a + # fragment. The answer must come from stdout. + printf 'import sys\nraise SystemExit("boom")\n' \ + > "${_broken}/pkg/scripts/lib/php_template_scope.py" + _expect_skip "${_BROKEN_RUNNER}" "a CRASHING classifier reports SKIPPED, not PASS (#249)" +else + _bad "could not stage a broken-helper copy of the package — wiring assertions did not run" +fi +rm -rf "${_broken}" + echo echo "== summary ==" printf ' passed: %d\n failed: %d\n' "${_pass_n}" "${_fail_n}" diff --git a/hydra-gates/scripts/run-hydra-gates.sh b/hydra-gates/scripts/run-hydra-gates.sh index 486c79e27..98bcbb89f 100755 --- a/hydra-gates/scripts/run-hydra-gates.sh +++ b/hydra-gates/scripts/run-hydra-gates.sh @@ -3350,9 +3350,14 @@ if [ -d src ] || [ -d templates ] || [ -d appinfo/templates ]; then # checker that greps a string literal misses every constant and matches # every comment, failing both ways at once. scripts/lib/php_template_scope.py # classifies EMITTED MARKUP, with PHP regions and HTML comments removed. - _sl_php_owns_document() { - python3 "${SCRIPT_DIR}/lib/php_template_scope.py" --owns-document "$1" 2>/dev/null - } + # + # THE ANSWER COMES FROM STDOUT, THE EXIT CODE IS A STATUS (gate-19 / #249). + # An earlier draft used the exit byte as the boolean — 0 owns, 1 fragment — + # and a helper that CRASHES also exits 1. Every template would have read as + # a fragment, the whole PHP arm would have evaporated, and the gate would + # have reported PASS on nothing. One `--classify` call for the whole set + # prints `: page-root|fragment`, and a non-zero exit is a wiring + # failure rather than an answer. _sl_check() { local _f="$1" _in_scope "$_f" || return 0 @@ -3412,10 +3417,32 @@ if [ -d src ] || [ -d templates ] || [ -d appinfo/templates ]; then _sl_ran=0 _skip 38 "skip-link" wiring "php_template_scope.py not found at ${_sl_helper} — ${#_sl_php[@]} PHP template(s) were in scope and NONE were classified; a document-owning template with no bypass mechanism (WCAG 2.4.1) is UNVERIFIED by this run." else - for _f in "${_sl_php[@]}"; do - _sl_php_owns_document "$_f" || continue - _sl_check "$_f" - done + _sl_cls_err="${HYDRA_GATE_LOG_DIR}/hydra-gate-skip-link.classify.err" + # gate-19's block (line ~1901) turns `set -e` ON and leaves it on + # for every gate after it, even though this script's own header + # sets only `set -u`. A helper that exits non-zero would therefore + # kill the whole runner mid-sweep — every LATER gate silently + # unreported — instead of reaching the _skip below. Measured: the + # crashing-classifier assertion aborted the run right here, 21 + # later gates lost. Disable errexit around the call and restore + # the caller's flag. + case $- in *e*) _sl_had_e=1 ;; *) _sl_had_e=0 ;; esac + set +e + _sl_cls=$(python3 "${_sl_helper}" --classify "${_sl_php[@]}" 2>"${_sl_cls_err}") + _sl_rc=$? + [ "${_sl_had_e}" -eq 1 ] && set -e + if [ "${_sl_rc}" -ne 0 ]; then + # The classifier fell over. It answered nothing, so there is no + # verdict to give — stderr is KEPT, not discarded (#249). + _sl_ran=0 + _skip 38 "skip-link" wiring "php_template_scope.py exited ${_sl_rc} — ${#_sl_php[@]} PHP template(s) were in scope and NONE were classified; a document-owning template with no bypass mechanism (WCAG 2.4.1) is UNVERIFIED by this run. See ${_sl_cls_err}." + else + while IFS= read -r _line; do + case "${_line}" in + *": page-root") _sl_check "${_line%: page-root}" ;; + esac + done <<< "${_sl_cls}" + fi fi fi _sl_fail=$(wc -l < "${_sl_log}" 2>/dev/null || echo 0) From a2fbcea07335e87edd57f3689e0662005fc4502e Mon Sep 17 00:00:00 2001 From: Ruben van der Linde Date: Sat, 8 Aug 2026 17:14:40 +0200 Subject: [PATCH 3/3] =?UTF-8?q?Merge=20origin/main=20into=20fix/gate-38=20?= =?UTF-8?q?=E2=80=94=20converge=20on=20=5Fa11y=5Fmarkup=5Ffiles,=20adopt?= =?UTF-8?q?=20the=20errexit=20invariant?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit TWO SCOPE DEFINITIONS BECOME ONE (#225 / #261). This arm had its own `find templates appinfo/templates -name '*.php'`, which is `_a11y_markup_files` minus its exclusions — so a generated `phpmetrics/` or a `vendor/` template would have been audited HERE and nowhere else in the a11y family. gate-38 now filters the shared enumeration to `*.php`. There is deliberately no third definition. ERREXIT (#243). Dropped the `case $- in *e*) … set -e` restore dance. main established that errexit is OFF for the whole script and nothing may turn it on — a trailing `set -e` is an unconditional ENABLE, not a restore. My workaround was written before that landed and is now obsolete; the underlying bug is fixed upstream, and test_gate_errexit_discipline.sh enforces the rule. Verified after the merge: skip-link control pairs 18/18, errexit discipline ALL PASS. --- hydra-gates/scripts/run-hydra-gates.sh | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/hydra-gates/scripts/run-hydra-gates.sh b/hydra-gates/scripts/run-hydra-gates.sh index d6845b20c..93e802134 100755 --- a/hydra-gates/scripts/run-hydra-gates.sh +++ b/hydra-gates/scripts/run-hydra-gates.sh @@ -3597,10 +3597,17 @@ if [ -d src ] || [ -d templates ] || [ -d appinfo/templates ]; then if [ -d templates ] || [ -d appinfo/templates ]; then _sl_helper="${SCRIPT_DIR}/lib/php_template_scope.py" _sl_php=() + # ONE SCOPE DEFINITION FOR THE FAMILY (#225 / #261). This arm used its + # own `find templates appinfo/templates -name '*.php'`, which is + # `_a11y_markup_files` minus the exclusions — so a generated + # phpmetrics/ or vendor/ template would have been audited here and + # nowhere else. Filtering the shared enumeration keeps the two from + # drifting, and there is deliberately no third definition. while IFS= read -r _f; do [ -z "$_f" ] && continue + case "$_f" in *.php) ;; *) continue ;; esac _in_scope "$_f" && _sl_php+=("$_f") - done < <(find templates appinfo/templates -name '*.php' 2>/dev/null) + done < <(_a11y_markup_files) if [ "${#_sl_php[@]}" -eq 0 ]; then : # nothing in scope; the verdict below describes the diff, as everywhere else. elif [ ! -f "${_sl_helper}" ]; then @@ -3611,19 +3618,15 @@ if [ -d src ] || [ -d templates ] || [ -d appinfo/templates ]; then _skip 38 "skip-link" wiring "php_template_scope.py not found at ${_sl_helper} — ${#_sl_php[@]} PHP template(s) were in scope and NONE were classified; a document-owning template with no bypass mechanism (WCAG 2.4.1) is UNVERIFIED by this run." else _sl_cls_err="${HYDRA_GATE_LOG_DIR}/hydra-gate-skip-link.classify.err" - # gate-19's block (line ~1901) turns `set -e` ON and leaves it on - # for every gate after it, even though this script's own header - # sets only `set -u`. A helper that exits non-zero would therefore - # kill the whole runner mid-sweep — every LATER gate silently - # unreported — instead of reaching the _skip below. Measured: the - # crashing-classifier assertion aborted the run right here, 21 - # later gates lost. Disable errexit around the call and restore - # the caller's flag. - case $- in *e*) _sl_had_e=1 ;; *) _sl_had_e=0 ;; esac + # `set +e` only, never `set -e` after. Errexit is OFF for this + # whole script and nothing may turn it on (#243, and the invariant + # at the top of this file). Before that landed, a non-zero helper + # here killed the entire runner mid-sweep instead of reaching the + # _skip below — measured at 21 later gates silently lost, the run + # ending on the abort banner. set +e _sl_cls=$(python3 "${_sl_helper}" --classify "${_sl_php[@]}" 2>"${_sl_cls_err}") _sl_rc=$? - [ "${_sl_had_e}" -eq 1 ] && set -e if [ "${_sl_rc}" -ne 0 ]; then # The classifier fell over. It answered nothing, so there is no # verdict to give — stderr is KEPT, not discarded (#249).