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
17 changes: 17 additions & 0 deletions .coderabbit.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -206,6 +206,20 @@ reviews:
GraphQL checks in schema.py; flag a second copy of either.
- TESTS use synthetic versions, shas and handles only; a value captured
from a live system in a fixture is a finding.
- path: ".github/unraid-compat/**"
instructions: |
The Unraid compatibility matrix; CI only, nothing here ships.
- install_test.sh puts the .plg through each Unraid version's own
plugin installer, hooks included, in a fresh Docker container with
no network; it must refuse to run anywhere else. Only Slackware's
upgradepkg and removepkg are stubbed, keeping their file-list
records: flag any other stand-in for Unraid's code.
- matrix_check.py keeps ci.yml's Unraid rows at one per minor from the
.plg's min to the newest release; Renovate only moves rows.
- Each step asserts what the user is left with (live files, the
registered manifest, saved folders, Unraid's orders) right after it,
against values written by hand. A failed step fails the job.
- Fixtures hold synthetic names and ids only.
- path: ".github/scripts/**"
instructions: |
CI tests and helpers; nothing here ships in the plugin.
Expand All @@ -224,6 +238,9 @@ reviews:
failed read or download as "nothing to report".
- package.json here is test-only (jquery, jsdom), pinned to exact
versions.
- php_tests.sh is the one list of PHP checks for Lint + build and the
PHP matrix: php -l on every .php and .page file, then every
*_test.php here; a deprecation fails like an error.
- path: "**"
instructions: |-
Applies to every file, whatever the language:
Expand Down
132 changes: 132 additions & 0 deletions .github/scripts/important_check.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,132 @@
#!/usr/bin/env python3
"""Each !important in the plugin's own CSS, JS, PHP and .page files needs a `!important: <reason>` comment."""
import pathlib
import re
import sys

import vendor

REASON = re.compile(r'!important:\s*\w', re.I)
KINDS = {'.css': 'css', '.js': 'js', '.php': 'php', '.page': 'page'}
# A `/` after one of these, or first on its line, opens a JS regex literal rather than dividing; not `<`, as `</p>` has it
REGEX_AFTER = set('(,=:[!&|?{};+-*%>~^')


def _blank(code, text, i, j):
code[i:j] = [ch if ch == '\n' else ' ' for ch in text[i:j]]


def _regex_end(text, i):
"""End of the JS regex literal opening at `i`, or None when the `/` divides."""
before = text[:i].rstrip(' \t')
if before and not before.endswith('\n') and before[-1] not in REGEX_AFTER and not re.search(r'\b(return|typeof)$', before):
return None
j, in_class = i + 1, False
while j < len(text) and text[j] != '\n':
if text[j] == '\\':
j += 1
elif text[j] == '[':
in_class = True
elif text[j] == ']':
in_class = False
elif text[j] == '/' and not in_class:
return j + 1
j += 1
return None


def _in_script(spans, i):
return any(start <= i < end for start, end in spans)


def scan(text, kind):
"""(code, comments): the text with comments, CSS strings and JS regexes blanked, and [(start, end, comment text)]."""
code, comments, i, n = list(text), [], 0, len(text)
script = kind != 'css'
# A .page holds CSS and HTML too: only its <script> blocks have regex literals (url(/x) in a <style> is not one),
# and only those and its PHP blocks have // comments (url(//cdn/x) is not one)
js = [(0, n)] if kind == 'js' else [m.span(1) for m in re.finditer(r'<script\b[^>]*>(.*?)</script>', text, re.I | re.S)] if kind == 'page' else []
slashes = [(0, n)] if kind in ('js', 'php') else js + [m.span(1) for m in re.finditer(r'<\?(.*?)(?:\?>|\Z)', text, re.S)] if kind == 'page' else []
while i < n:
c, two = text[i], text[i:i + 2]
html = kind == 'page' and text.startswith('<!--', i)
# `//` after a `:` is a URL (https://), not a comment
if two == '/*' or html or (two == '//' and text[i - 1:i] != ':' and _in_script(slashes, i)) or (kind == 'php' and c == '#' and text[i + 1:i + 2] != '['):
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Resolved
close = '*/' if two == '/*' else '-->' if html else '\n'
found = text.find(close, i + 2)
end = n if found == -1 else found + (0 if close == '\n' else len(close))
comments.append((i, end, text[i:end]))
_blank(code, text, i, end)
i = end
elif c == '/' and _in_script(js, i) and (end := _regex_end(text, i)):
_blank(code, text, i, end)
i = end
elif c in '"\'' or (c == '`' and script):
j = i + 1
while j < n and text[j] != c and text[j] != '\n':
Comment thread
chodeus marked this conversation as resolved.
Resolved
j += 2 if text[j] == '\\' else 1
# A script's string is where inline styles live: keep it as code; a CSS string (content: "...") is text
if kind == 'css':
_blank(code, text, i, j + 1)
i = j + 1
else:
i += 1
return ''.join(code), comments


def _line(text, at):
return text.count('\n', 0, at)


def _own_line(text, start):
return text[text.rfind('\n', 0, start) + 1:start].strip() == ''


def _reason(comments, text, line, alone):
"""A reason comment ending on `line`; with `alone`, only one with no code before it on its line."""
return any(REASON.search(body) and _line(text, end - 1) == line and (not alone or _own_line(text, start))
for start, end, body in comments)


def _rule_start(code, at):
"""Where the selector of the rule holding the declaration at `at` begins, past any nested rules; None outside a rule."""
depth, opened = 0, at - 1
while opened >= 0 and not (code[opened] == '{' and depth == 0):
depth += (code[opened] == '}') - (code[opened] == '{')
opened -= 1
if opened < 0:
return None
start = max(code.rfind(ch, 0, opened) for ch in '{};') + 1
while start < opened and code[start].isspace():
start += 1
return start


def problems_in(path, text, kind):
code, comments = scan(text, kind)
out = []
for m in re.finditer(r'!\s*important\b', code, re.I):
line = _line(text, m.start())
ok = _reason(comments, text, line, alone=False) or _reason(comments, text, line - 1, alone=True)
start = _rule_start(code, m.start()) if kind == 'css' else None
if not ok and start is not None:
ok = _reason(comments, text, _line(text, start) - 1, alone=True) or _reason(comments, text, _line(text, start), alone=True)
if not ok:
out.append(f'{path}:{line + 1}: !important without a "!important: <reason>" comment on its line, the line above, or above its rule')
return out


def problems(repo):
repo = repo.resolve()
manifest, root = vendor.plugin_root(repo)
bundled = {vendor.destination(manifest, root, dest) for lib in manifest['libraries'] for dest in lib['files'].values()}
files = [p for p in sorted(root.rglob('*')) if p.suffix in KINDS and p.is_file() and p.resolve() not in bundled]
if not files:
return [f'{manifest["root"]}: no CSS, JS, PHP or .page files to check']
return [problem for p in files for problem in problems_in(p.relative_to(repo), p.read_text(encoding='utf-8'), KINDS[p.suffix])]


if __name__ == '__main__':
found = problems(pathlib.Path(__file__).resolve().parents[2])
print('\n'.join(found) or 'Every !important has its reason')
sys.exit(1 if found else 0)
98 changes: 98 additions & 0 deletions .github/scripts/important_check_test.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
import json
import pathlib
import tempfile
import unittest

import important_check

ROOT = 'src/plugin'


class ImportantCheckTest(unittest.TestCase):
def check(self, files, bundled=()):
tmp = tempfile.TemporaryDirectory()
self.addCleanup(tmp.cleanup)
repo = pathlib.Path(tmp.name)
(repo / 'vendor.json').write_text(json.dumps({'root': ROOT, 'libraries': [{'files': {f'x/{b}': b for b in bundled}}]}), encoding='utf-8')
for name, text in files.items():
(repo / ROOT / name).parent.mkdir(parents=True, exist_ok=True)
(repo / ROOT / name).write_text(text, encoding='utf-8')
return important_check.problems(repo)

def test_a_reason_above_the_rule_or_on_the_line_passes(self):
sheet = ('.a { top: 0 }\n\n/* !important: Unraid inlines this padding */\n#t .x,\n#t .y {\n padding-left: 20px !important;\n}\n'
'.b { margin: 0 !important; /* !important: a theme sets it inline */ }\n')
self.assertEqual(self.check({'styles/a.css': sheet}), [])

def test_an_important_without_its_reason_is_named_with_its_line(self):
sheet = '/* spacing */\n.a {\n top: 0;\n left: 1px!important;\n}\n'
self.assertEqual(self.check({'styles/a.css': sheet}),
[f'{ROOT}/styles/a.css:4: !important without a "!important: <reason>" comment on its line, the line above, or above its rule'])

def test_a_reason_belongs_to_the_rule_under_it_only(self):
sheet = '/* !important: first */\n.a { top: 0 !important }\n.b { top: 0 !important }\n'
(problem,) = self.check({'styles/a.css': sheet})
self.assertIn('a.css:3:', problem)

def test_a_reason_at_the_end_of_a_line_covers_that_line_only(self):
rules = '.a { top: 0 !important } /* !important: r */\n.b { top: 0 !important }\n'
decls = '.c {\n top: 0 !important; /* !important: r */\n left: 0 !important;\n}\n'
self.assertEqual([p.split(': !')[0] for p in self.check({'styles/a.css': rules, 'styles/b.css': decls})],
[f'{ROOT}/styles/a.css:2', f'{ROOT}/styles/b.css:3'])

def test_a_nested_rule_does_not_move_a_declaration_to_its_selector(self):
outer = '/* !important: r */\n.a {\n .b { color: red }\n top: 0 !important;\n}\n'
inner = '.a {\n /* !important: r */\n .b { color: red }\n top: 0 !important;\n}\n'
self.assertEqual(self.check({'styles/a.css': outer}), [])
(problem,) = self.check({'styles/b.css': inner})
self.assertIn('b.css:4:', problem)

def test_a_quote_in_a_regex_literal_or_a_php_hash_comment_is_read_as_code_does(self):
js = "s = s.replace(/'/g, ''); el.style.cssText = 'x:1 !important'; // !important: r\n"
php = "<?php\n# !important: r\necho '.b{top:0 !important}';\n"
self.assertEqual(self.check({'scripts/a.js': js, 'server/a.php': php}), [])

def test_any_case_a_url_or_an_html_reason_is_read_as_the_browser_does(self):
found = self.check({'styles/a.css': '.a { top: 0 !IMPORTANT }\n',
'Folder.page': '<p>See https://example.test</p><style>.b { top: 0 !important }</style>\n<!-- !important: r -->\n<i style="top:0 !important"></i>\n'})
self.assertEqual([p.split(': !')[0] for p in found], [f'{ROOT}/Folder.page:1', f'{ROOT}/styles/a.css:1'])

def test_a_url_in_page_css_is_no_regex_but_one_in_its_script_is(self):
page = ('<style>.a { background: url(/icon.svg); color: red !important; }</style>\n'
"<script>s = s.replace(/'/g, ''); el.style.cssText = 'x:1 !important'; // !important: r\n</script>\n")
(problem,) = self.check({'Folder.page': page})
self.assertIn('Folder.page:1:', problem)

def test_a_protocol_relative_url_in_page_css_is_no_comment_but_one_in_its_php_is(self):
page = '<style>.a { background: url(//cdn.test/x.png); color: red !important; }</style>\n<?php\n// !important: r\necho "<i style=\'top:0 !important\'>"; ?>\n'
(problem,) = self.check({'Folder.page': page})
self.assertIn('Folder.page:1:', problem)

def test_no_files_to_check_fails_closed(self):
self.assertEqual(self.check({'README.md': 'x'}), [f'{ROOT}: no CSS, JS, PHP or .page files to check'])

def test_a_reason_comment_must_give_a_reason(self):
self.assertEqual(len(self.check({'styles/a.css': '/* !important: */\n.a { top: 0 !important }\n'})), 1)

def test_a_comment_or_a_content_string_that_mentions_it_is_not_a_use(self):
sheet = '/* never use !important here */\n.a::after { content: "!important"; }\n'
self.assertEqual(self.check({'styles/a.css': sheet}), [])

def test_a_script_needs_the_reason_on_its_line_or_the_line_above(self):
good = "// beats swal's !important rules\n// !important: no stylesheet may show a row while it is measured\nrow.style.cssText += ';visibility:hidden !important;';\n"
bad = "// hide the row\nrow.style.cssText += ';visibility:hidden !important;';\n"
self.assertEqual(self.check({'scripts/a.js': good}), [])
(problem,) = self.check({'scripts/b.js': bad})
self.assertIn('scripts/b.js:2:', problem)

def test_page_and_php_files_are_checked_too(self):
found = self.check({'Folder.page': 'Menu="x"\n---\n<style>.a { top: 0 !important }</style>\n', 'server/a.php': "<?php echo '.b{top:0 !important}';\n"})
self.assertEqual([p.split(':')[0] for p in found], [f'{ROOT}/Folder.page', f'{ROOT}/server/a.php'])

def test_a_bundled_library_is_skipped(self):
self.assertEqual(self.check({'styles/include/lib.css': '.a { top: 0 !important }\n', 'styles/own.css': '.b { top: 0 }\n'},
bundled=['styles/include/lib.css']), [])


if __name__ == '__main__':
unittest.main()
37 changes: 37 additions & 0 deletions .github/scripts/php_tests.sh
Original file line number Diff line number Diff line change
@@ -0,0 +1,37 @@
#!/bin/bash
# php -l over every plugin .php and .page file, then every .github/scripts/*_test.php, with every error level on.
# Every PHP process logs to one file, the endpoints the tests start included; a deprecation there fails like an error.
set -u
cd "$(dirname "$0")/../.." || exit 2
status=0
ini=$(mktemp -d)
trap 'rm -rf "$ini"' EXIT
log=$ini/errors.log
: > "$log"
printf 'error_reporting=-1\nlog_errors=1\nerror_log=%s\n' "$log" > "$ini/zz-fv3-tests.ini"
# An empty entry keeps PHP's own scan folder; this file loads after it, in every child process too
export PHP_INI_SCAN_DIR="${PHP_INI_SCAN_DIR:-}:$ini"
php -v | head -1
php -r 'exit((error_reporting() & E_ALL) === E_ALL && ini_get("log_errors") ? 0 : 1);' || { echo 'FAILED: the error-log settings did not load'; exit 1; }

deprecated() { # deprecated <step>: fails the run when <step> logged a deprecation
local seen; seen=$(grep -c 'Deprecated:' "$log")
if [ "$seen" -gt "${logged:-0}" ]; then
echo "FAILED: $1 ran into a deprecation:"
grep 'Deprecated:' "$log" | tail -n "$((seen - ${logged:-0}))"
status=1
fi
logged=$seen
}

while IFS= read -r -d '' f; do
php -l "$f" >/dev/null 2>&1 || { php -l "$f"; status=1; }
done < <(find src \( -name '*.php' -o -name '*.page' \) -print0)
deprecated 'php -l'

for t in .github/scripts/*_test.php; do
echo "== $t"
php -d display_errors=stderr "$t" || status=1
deprecated "$t"
done
exit $status
21 changes: 16 additions & 5 deletions .github/scripts/vendor.py
Original file line number Diff line number Diff line change
Expand Up @@ -95,12 +95,25 @@ def lf(data):
return data if b'\0' in data[:8000] else data.replace(b'\r\n', b'\n')


def plugin_root(repo=ROOT):
"""(vendor.json, the plugin folder its root names)."""
manifest = json.loads((repo / 'vendor.json').read_text())
return manifest, (repo / manifest['root']).resolve()


def destination(manifest, root, rel):
"""Where a bundled file lands; vendor.json may not point outside the plugin folder."""
dest = (root / rel).resolve()
if not dest.is_relative_to(root):
raise SystemExit(f'vendor.json: {rel} is outside {manifest["root"]}')
return dest


def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('mode', choices=('check', 'sync'))
mode = parser.parse_args().mode
manifest = json.loads((ROOT / 'vendor.json').read_text())
root = (ROOT / manifest['root']).resolve()
manifest, root = plugin_root()
stale = []
for lib in manifest['libraries']:
if 'npm' in lib:
Expand All @@ -110,9 +123,7 @@ def main():
else:
raise SystemExit(f'vendor.json: a library needs an npm or github source: {lib}')
for src, data in files.items():
dest = (root / lib['files'][src]).resolve()
if not dest.is_relative_to(root):
raise SystemExit(f'vendor.json: {lib["files"][src]} is outside {manifest["root"]}')
dest = destination(manifest, root, lib['files'][src])
data = lf(data)
if dest.is_file() and dest.read_bytes() == data:
continue
Expand Down
5 changes: 5 additions & 0 deletions .github/unraid-compat/Dockerfile
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
# The PHP an Unraid version ships, plus what Unraid has and this image lacks: gawk (the .plg's remove script uses RT), xz
# (the package format) and wget (the installer's downloader, so a download fails on the network, not a missing tool).
ARG PHP
FROM php:${PHP}-cli
RUN apt-get update && apt-get install -y --no-install-recommends gawk wget xz-utils && rm -rf /var/lib/apt/lists/*
Loading
Loading