Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
97 changes: 97 additions & 0 deletions hydra-gates/scripts/lib/php_template_scope.py
Original file line number Diff line number Diff line change
@@ -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 `<html>` / `<body>` 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 `<div id="procest-settings"></div>`, 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 `<html>`, 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:

* `<?php … ?>` 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 <file> # exit 0 = owns, 1 = fragment
php_template_scope.py --classify <file>... # "<path>: page-root|fragment"
"""
from __future__ import annotations

import re
import sys

# `<?php … ?>` 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 `<html>` or `<body>` 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))
77 changes: 77 additions & 0 deletions hydra-gates/scripts/lib/test_gate_monitoring_and_skiplink.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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 <NcContent> shell' \
"accidental: gate-38 names the root component"
# #214/#216 — the PHP half must keep a true positive. `standalone.php`
# emits <html> and <body>: it owns the document, so SC 2.4.1 is its to
# satisfy, and it does not.
_expect_log "${_SLLOG}" 'templates/standalone\.php: no <NcContent> shell' \
"accidental: a PHP template that OWNS the document and has no bypass link is still reported"
fi

# ---------------------------------------------------------------------------
Expand All @@ -128,8 +133,80 @@ 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 (<div id=...> 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

# ---------------------------------------------------------------------------
# 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() { # <runner> <description>
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:-<no gate-38 line at all>}" ;;
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}"
Expand Down
149 changes: 149 additions & 0 deletions hydra-gates/scripts/lib/test_php_template_scope.py
Original file line number Diff line number Diff line change
@@ -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 `<html>`, 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(
"<?php\nscript('procest', 'admin');\n?>\n"
'<div id="procest-settings"></div>\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(
'<div id="nldesign-settings" class="section">\n'
' <h2>NL Design System Theme</h2>\n'
' <label for="ts">Design token set</label>\n'
' <select id="ts"><option>a</option></select>\n'
'</div>\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 <html> element must not
# be read as this file emitting one.
self.assertFalse(pts.owns_document(
"<?php\n"
"// Core emitted this page's <html> and <body> long before this\n"
"// file's first byte; this template is only a mount point.\n"
"?>\n"
'<div id="fixture-settings"></div>\n'))

def test_a_docblock_naming_body_does_not_make_it_a_page_root(self):
self.assertFalse(pts.owns_document(
"<?php\n/**\n * Substituted into core's <body>.\n */\n?>\n"
'<div id="x"></div>\n'))

def test_commented_out_markup_ships_nothing(self):
self.assertFalse(pts.owns_document(
'<!-- <html><body>an older, abandoned standalone page</body></html> -->\n'
'<div id="x"></div>\n'))

def test_an_all_php_file_owns_no_document(self):
self.assertFalse(pts.owns_document("<?php\nreturn ['a' => 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(
'<!DOCTYPE html>\n<html lang="en">\n<head><title>x</title></head>\n'
'<body><div id="app"></div></body>\n</html>\n'))

def test_body_alone_is_enough(self):
# Some standalone templates are included after a partial header.
self.assertTrue(pts.owns_document('<body class="public">\n<p>hi</p>\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(
"<?php\n$title = 'x';\n?>\n<html lang=\"en\"><body>hi</body></html>\n"))

def test_html_between_two_php_blocks(self):
self.assertTrue(pts.owns_document(
"<?php $a = 1; ?>\n<html lang=\"en\">\n<?php echo $a; ?>\n"
"<body>hi</body></html>\n"))

def test_uppercase_tags(self):
self.assertTrue(pts.owns_document('<HTML LANG="en"><BODY>hi</BODY></HTML>'))

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(
'<!-- a standalone public page; core does not wrap this -->\n'
'<html lang="nl"><body><p>hi</p></body></html>\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("<?php\n// <html> 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', '<html lang="en"><body>hi</body></html>')
frag = self._write(tmp, 'frag.php', '<div id="x"></div>')
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)
Loading
Loading