diff --git a/.github/unraid-watch/README.md b/.github/unraid-watch/README.md index 7d20aef2..5b2eab3f 100644 --- a/.github/unraid-watch/README.md +++ b/.github/unraid-watch/README.md @@ -7,11 +7,14 @@ plugin stands. Both go to issue #52. - **check** (every CI run, offline). Reads each GraphQL document out of `scripts/*.js` and `*.page`, and each webgui PHP file the plugin references. Fails when a document is not a plain string, because nothing - downstream could see it. + downstream could see it. Also fails on a `var(--x)` in the plugin's stylesheets with no fallback when only + Unraid defines `--x`, so an Unraid release without it cannot drop the style; a variable the plugin's own + stylesheets declare, or its scripts or server code name (the CSS tool's presets), is the plugin's. - **contract** (pull requests that touch `src/`, this directory or the workflow file, every push to `main` or `beta`, and daily for both). Validates every operation against the `unraid/api` schema on `main` and at the - latest release, and confirms every watched path still exists upstream. Red means the plugin sends something - that is no longer valid, or a file it depends on is gone. The daily run checks each branch with that branch's + latest release, confirms every watched path still exists upstream, and checks every contract on each stable + webgui release tag from the plugin's declared minimum and on the development branch. Red means the plugin sends + something that is no longer valid, a file it depends on is gone, or a release it supports breaks a contract. The daily run checks each branch with that branch's copy of the tool; a manual run checks the branch it is started on. - **watch** (daily, on every push to `beta`, and by hand). It always reads the plugin on `beta`, whichever branch starts it, and does two things: @@ -39,8 +42,14 @@ Once it is on `main` the daily run starts by itself, and still reads `beta`. - **Coming with X.Y**: what the newest OS pre-release has that the newest stable does not. - **Operations by OS release**: how many of the plugin's operations are valid on the API each OS release bundles, and which fields are missing. +- **Contracts by OS release**: whether each contract holds on every webgui release tag from the plugin's minimum + and on the development branch. An OS release the webgui has no tag for (some patch releases) is not read. +- **Unraid CSS by OS release**: per theme, the layout properties Unraid's stylesheets set on an element the + plugin's own CSS styles, that differ between releases, and that the plugin does not set itself: what can + look different on an older or newer Unraid. A rule no longer set on the development branch is listed apart, + as it has often only moved to a stylesheet not read here. - **API not used yet**: Docker and VM operations the plugin never calls, and how much of each type it reads. -- **Still on legacy**: the webgui files the plugin still depends on. +- **Still on legacy**: the webgui files the plugin still depends on, stylesheets aside. OS versions and the API each one bundles are read from the release notes. They state it in prose, in several styles; a release whose notes do not say is listed as not stated rather than guessed. Files are compared by @@ -63,6 +72,12 @@ with `' + name + '` when `watch.json` has an `expand` rule naming the JS map tha operation from an unread field. - `releases`: directory holding the OS release notes. `since` is the oldest OS release to list, and `tags` is the repository whose tags carry those OS versions. +- `manifest`: the plugin's `.plg`. Its `min` attribute is the oldest OS release the contracts and stylesheets + are checked on; the webgui's stable tags from there up are the releases, and finding none is an error. +- `contracts`: what the plugin relies on in a webgui file, as a `path`, a regular expression it must `match`, + and `why`. Optional `since`: the oldest release held to it. Add one with each change that relies on Unraid. +- `styles`: the `themes`, and the stylesheet `files` that make up each one in load order (`{theme}` is + replaced). A file a release does not have is skipped, so files from older and newer layouts can both be listed. ## Running it by hand diff --git a/.github/unraid-watch/css.py b/.github/unraid-watch/css.py new file mode 100644 index 00000000..a0e08f48 --- /dev/null +++ b/.github/unraid-watch/css.py @@ -0,0 +1,185 @@ +"""Stylesheets, FolderView3's and Unraid's: rules as text, the elements FolderView3 styles, and what Unraid sets on them per release.""" +import re + +TOKEN = re.compile(r'[#.][A-Za-z_][\w-]*') +COMMENT = re.compile(r'/\*.*?\*/', re.S) +VAR = re.compile(r'var\(\s*(--[\w-]+)\s*([,)])') +DEFINED = re.compile(r'(?:^|[;{\s])(--[\w-]+)\s*:') +# At-rules whose block holds rules for elements; @keyframes, @font-face and @page hold none +GROUPS = ('@media', '@supports', '@container', '@layer', '@scope') +# What moves or wraps an element. Colours and fonts change with each theme by design, so they are left out +LAYOUT = frozenset({ + 'display', 'position', 'white-space', 'overflow', 'overflow-x', 'overflow-y', 'float', 'clear', 'box-sizing', 'flex', 'flex-direction', + 'flex-wrap', 'flex-grow', 'flex-shrink', 'flex-basis', 'align-items', 'justify-content', 'gap', 'grid-template-columns', 'width', + 'min-width', 'max-width', 'height', 'min-height', 'max-height', 'margin', 'margin-top', 'margin-bottom', 'margin-left', 'margin-right', + 'padding', 'padding-top', 'padding-bottom', 'padding-left', 'padding-right', 'line-height', 'font-size', 'vertical-align', 'text-align', + 'text-overflow', 'word-break', 'overflow-wrap', 'table-layout', 'border-collapse', 'border-spacing', 'top', 'left', 'right', 'bottom', + 'transform', 'z-index', 'visibility', 'content'}) + + +def uncommented(text): + """The text with each comment blanked out, line breaks kept so positions still give line numbers.""" + return COMMENT.sub(lambda m: '\n' * m.group(0).count('\n'), text) + + +def _plain(text): + """[(index, char)] for characters outside quoted strings, so a "}" or ";" in a content value is just text.""" + out, quote = [], None + for i, c in enumerate(text): + if quote: + quote = None if c == quote and text[i - 1] != '\\' else quote + elif c in '"\'': + quote = c + else: + out.append((i, c)) + return out + + +def _split(text, at): + """text cut at each `at` character outside parentheses and strings (a url() or :not() list keeps its ; and ,).""" + parts, depth, start = [], 0, 0 + for i, c in _plain(text): + depth += (c == '(') - (c == ')') + if c == at and depth <= 0: + parts.append(text[start:i]) + start = i + 1 + return parts + [text[start:]] + + +def _selector(text): + """One spelling per selector: spacing around combinators and quotes around attribute values do not make a rule new.""" + text = re.sub(r'\s*([>+~])\s*', r' \1 ', text) + text = re.sub(r'\[\s*([\w-]+)\s*([~|^$*]?=)\s*["\']?([^"\'\]]*?)["\']?\s*\]', r'[\1\2\3]', text) + return ' '.join(text.split()) + + +def _condition(text): + """One spelling per at-rule condition, `@media (max-width: 767px)`, however the stylesheet spaced it.""" + text = re.sub(r'\s*([():,])\s*', r'\1', text) + text = re.sub(r'(?<=[\w)])\(', ' (', text).replace(':', ': ').replace(',', ', ') + return ' '.join(text.split()) + + +def _parts(body): + """[(None, declarations) or (head, block)] of a body in source order: its own declarations and the rules nested in it.""" + items, depth, paren, start, item = [], 0, 0, 0, 0 + for i, c in _plain(body): + paren += (c == '(') - (c == ')') if depth == 0 else 0 + if c == '{': + if depth == 0: + items.append((None, body[start:item])) + head, opened = ' '.join(body[item:i].split()), i + 1 + depth += 1 + elif c == '}' and depth: + depth -= 1 + if depth == 0: + items.append((head, body[opened:i])) + start = item = i + 1 + elif c == ';' and depth == 0 and paren <= 0: + item = i + 1 + return items + [(None, body[start:])] + + +def _set(decls, name, value): + """A later declaration wins, except over an !important one that it is not itself.""" + if not (decls.get(name, '').endswith('!important') and not value.endswith('!important')): + decls[name] = value + + +def _declarations(text): + decls = {} + for part in _split(text, ';'): + name, colon, value = part.partition(':') + if colon and name.strip() and not name.strip().startswith('@'): + # `4px!important` and `4px !important` are the same value + _set(decls, name.strip().lower(), ' '.join(re.sub(r'\s*!\s*important\b', ' !important', value).split())) + return decls + + +def _walk(body, conditions, parents, out): + # In source order: a declaration after a nested rule comes after it, as the browser applies them + for head, block in _parts(body): + if head is None: + decls = _declarations(block) if parents else {} + out += [(conditions, parent, decls) for parent in parents if decls] + continue + if head.startswith('@'): + # `@media(max-width:600px)` needs no space after the keyword + if re.match(r'@[\w-]+', head).group(0).lower() in GROUPS: + _walk(block, ' '.join(filter(None, (conditions, _condition(head)))), parents, out) + continue + selectors = [_selector(s) for s in _split(head, ',') if s.strip()] + # Nesting: & is the parent rule; a nested selector without one is a descendant of it + resolved = [s.replace('&', p) if '&' in s else f'{p} {s}' for p in parents for s in selectors] if parents else selectors + _walk(block, conditions, resolved, out) + + +def rules(text): + """[(at-rule conditions, selector, {property: value})] in document order, nested rules resolved.""" + out = [] + _walk(uncommented(text), '', [], out) + return out + + +def subject(selector): + """The ids and classes of the element a selector styles; none for a ::before box, nothing an attribute value or :not() names.""" + # Innermost first, until none is left: 7.4 wraps its guards as :where(:not(.unapi *)) + bare, previous = re.sub(r'\[[^\]]*\]', '', selector), None + while bare != previous: + bare, previous = re.sub(r'\([^()]*\)', '', bare), bare + last = re.split(r'[\s>+~]+', bare.strip())[-1] + return [] if '::' in last else TOKEN.findall(last) + + +def styled(texts): + """{id or class: {(at-rule conditions, property)} FolderView3 sets on elements that carry it} from its own stylesheets.""" + out = {} + for text in texts: + for conditions, selector, decls in rules(text): + for token in subject(selector): + out.setdefault(token, set()).update((conditions, name) for name in decls) + return out + + +def merged(texts): + """{(at-rule conditions, selector, property): value} for stylesheets in load order: a later one wins, !important aside.""" + out = {} + for text in texts: + for conditions, selector, decls in rules(text): + for name, value in decls.items(): + _set(out, (conditions, selector, name), value) + return out + + +def _covers(ours, token, conditions, name): + # The plugin's own rule for this property covers Unraid's when it holds everywhere, or under the same condition + return ('', name) in ours[token] or (conditions, name) in ours[token] + + +def changes(by_ref, refs, ours): + """[(conditions, selector, property, [(ref, value)])]: layout Unraid changed on elements FolderView3 styles but does not set.""" + out = [] + for conditions, selector, name in sorted(set().union(*(by_ref[r] for r in refs))): + tokens = [t for t in subject(selector) if t in ours] + if name not in LAYOUT or not tokens or any(_covers(ours, t, conditions, name) for t in tokens): + continue + values = [(ref, by_ref[ref].get((conditions, selector, name))) for ref in refs] + if len({v for _, v in values}) > 1: + out.append((conditions, selector, name, values)) + return out + + +def fallbacks(stylesheets, code): + """Problems: var(--x) with no fallback where --x is Unraid's, not declared or keyed by FolderView3's own CSS or code.""" + texts = {f: uncommented(f.read_text(encoding='utf-8')) for f in stylesheets} + ours = {name for text in texts.values() for name in DEFINED.findall(text)} + named = '\n'.join(f.read_text(encoding='utf-8') for f in code) + + def keyed(name): + # The CSS tool's presets ('fv3-x': '#fff') and the generated theme CSS ('x' => '#fff') key the plugin's own variables; + # a name that is only read (getPropertyValue('--x')) is not defined by that + return re.search(r"['\"](?:--)?" + re.escape(name[2:]) + r"['\"]\s*(?::|=>)", named) + return [f'{f.name}:{text.count(chr(10), 0, m.start()) + 1}: var({m.group(1)}) has no fallback and FolderView3 does not ' + f'define {m.group(1)}, so the style needs every Unraid release to; give it a fallback' + for f, text in texts.items() for m in VAR.finditer(text) + if m.group(2) == ')' and m.group(1) not in ours and not keyed(m.group(1))] diff --git a/.github/unraid-watch/github.py b/.github/unraid-watch/github.py index 64911d7f..4e49da31 100644 --- a/.github/unraid-watch/github.py +++ b/.github/unraid-watch/github.py @@ -112,6 +112,22 @@ def read(): return self._call('GET', f'/repos/{repo}/contents/{urllib.parse.quote(path)}', {'ref': ref}, raw=True) return self._once(('file', repo, ref, path), read) + def blob(self, repo, sha): + """A file's text by its blob sha: one read per version of a file, however many releases share it.""" + return self._once(('blob', repo, sha), lambda: self._call('GET', f'/repos/{repo}/git/blobs/{sha}', raw=True)) + + def tags(self, repo): + """Every tag name of a repository.""" + def read(): + names = [] + for page in range(1, 51): + batch = self._call('GET', f'/repos/{repo}/tags', {'page': page, 'per_page': 100}) + names += [t['name'] for t in batch] + if len(batch) < 100: + return names + raise GitHubError(f'{repo}: more than 5000 tags') + return self._once(('tags', repo), read) + def exists(self, repo, ref, path): return bool(self._call('HEAD', f'/repos/{repo}/contents/{urllib.parse.quote(path.rstrip("/"))}', {'ref': ref}, missing=(404,))) diff --git a/.github/unraid-watch/releases.py b/.github/unraid-watch/releases.py index f8a09aa0..05ac29f2 100644 --- a/.github/unraid-watch/releases.py +++ b/.github/unraid-watch/releases.py @@ -16,6 +16,12 @@ def stable(version): return '-' not in version +def os_tag(name): + """A stable Unraid OS release tag such as 7.4.0; the webgui's oldest tags are dates such as 2014.11.10.""" + found = VERSION.fullmatch(name) + return bool(found) and stable(name) and int(found.group(1)) < 1000 + + def heading(text): """First markdown heading of a release-notes file; '' when it has none.""" for line in text.splitlines(): diff --git a/.github/unraid-watch/report.py b/.github/unraid-watch/report.py index 41366faa..f6af135a 100644 --- a/.github/unraid-watch/report.py +++ b/.github/unraid-watch/report.py @@ -91,6 +91,59 @@ def _changed(commits): return f'{len(commits)} commit{"" if len(commits) == 1 else "s"}, newest {code(f"{date} {subject}")}' +def _runs(values): + """`a` in `7.0.0`–`7.3.5`, not set in `7.4.0`–`master`: consecutive refs with the same value as one span.""" + runs = [] + for ref, value in values: + if runs and runs[-1][0] == value: + runs[-1][2] = ref + else: + runs.append([value, ref, ref]) + return ', '.join(f'{"not set" if value is None else code(value)} in {code(a)}' + ('' if a == b else f'–{code(b)}') + for value, a, b in runs) + + +def _contracts(view): + if 'unread' in view: + return ['', f'**Contracts and Unraid CSS by OS release**: could not be read ({code(view["unread"], 300)}).'] + *tags, branch = view['refs'] + span = f'{code(tags[0])} to {code(tags[-1])}' if len(tags) > 1 else code(tags[0]) + out = ['', '**Contracts by OS release**', '', + f'What FolderView3 relies on in the webgui, checked on its release tags {span} and on {code(branch)}.', ''] + for entry, found in view['contracts']: + held = [ref for ref, ok in found.items() if ok is not None] + broken = [f'{"missing" if ok == "missing" else "fails"} on {code(ref)}' for ref, ok in found.items() if ok not in (True, None)] + since = f' (from {code(entry["since"])})' if 'since' in entry else '' + out.append(f'- {code(entry["path"].rsplit("/", 1)[-1])} {entry["why"]}: ' + + (', '.join(broken) if broken else f'holds on all {len(held)}') + since) + return out + + +def _styles(view): + if 'unread' in view: + return [] + themes, changed, gone = list(view['styles']), {}, {} + for theme, rows in view['styles'].items(): + for context, selector, name, values in rows: + # Not set on the development branch any more: often a rule that moved to a stylesheet this does not read + (gone if values[-1][1] is None else changed).setdefault((context, selector, name, tuple(values)), []).append(theme) + + def row(key, who): + context, selector, name, values = key + where = '' if len(who) == len(themes) else f' ({", ".join(who)})' + return f'- {code((context + " " if context else "") + selector, 200)} {code(name)}: {_runs(values)}{where}' + out = ['', '**Unraid CSS by OS release**', '', + 'Layout properties Unraid sets on elements FolderView3 styles, that differ between releases, and that FolderView3 ' + 'does not set itself.', ''] + out += capped([row(k, w) for k, w in changed.items()], 40) or ['- none'] + if view['unmatched']: + out += ['', 'Listed in watch.json but on no release: ' + ', '.join(code(p, 200) for p in view['unmatched']) + '.'] + if gone: + out += ['', f'
No longer set in the stylesheets read here ({len(gone)}; may have moved elsewhere)', ''] + out += capped([row(k, w) for k, w in gone.items()], 40) + ['', '
'] + return out + + def render_status(view): newest, stable, latest = view['releases'] facts = [f'Newest OS release {code(newest[0])} (API {code(newest[1] or "not stated")})'] if newest else [] @@ -124,6 +177,8 @@ def render_status(view): + ', '.join(f'{code(name)} {read}/{total}' for name, read, total in view['types']) + '.'] out += ['', '', '', f'
Still on legacy ({len(view["legacy"])} webgui files)', ''] out += [f'- {code(path, 200)}: {why}' for path, why in view['legacy']] + ['', '
'] + # Last: the longest sections, so a body cut for length loses these before anything above + out += _contracts(view) + _styles(view) return fit('\n'.join(out)) + '\n\n' + STATUS diff --git a/.github/unraid-watch/scan.py b/.github/unraid-watch/scan.py index 15ac1f9b..0abd44a0 100644 --- a/.github/unraid-watch/scan.py +++ b/.github/unraid-watch/scan.py @@ -65,6 +65,21 @@ def operations(plugin, rules): return ops, problems +def stylesheets(plugin): + return _files(plugin, ('styles/*.css',)) + + +def code(plugin): + """The scripts and server code, which name the plugin's own CSS variables (the CSS tool, the generated theme CSS).""" + return _files(plugin, ('scripts/*.js', 'server/*.php')) + + +def minimum(manifest): + """The oldest Unraid release the plugin declares it runs on: the PLUGIN tag's min attribute; None when it has none.""" + found = re.search(r']*\bmin="(\d+\.\d+\.\d+)"', manifest.read_text(encoding='utf-8')) + return found and found.group(1) + + def endpoints(plugin, prefixes): """{upstream path: file:line} for every webgui PHP file the plugin references by URL or include.""" found = {} diff --git a/.github/unraid-watch/status.py b/.github/unraid-watch/status.py index d6414760..d40d6e90 100644 --- a/.github/unraid-watch/status.py +++ b/.github/unraid-watch/status.py @@ -2,6 +2,7 @@ import releases import schema import upstream +from github import GitHubError def stage(gh, cfg, ops, watched, spans): @@ -20,8 +21,8 @@ def stage(gh, cfg, ops, watched, spans): return out -def gather(gh, cfg, ops, watched, heads): - """Everything the status comment shows, as plain data.""" +def gather(gh, cfg, ops, watched, heads, local): + """Everything the status comment shows, as plain data; local is watch.local(): the plugin's floor and styled elements.""" api, docs = upstream.source(cfg, 'schema'), upstream.source(cfg, 'releases') core, tagged = api['repo'], docs['tags'] branch = next(s['branch'] for s in cfg['sources'] if s['repo'] == tagged) @@ -59,5 +60,16 @@ def bundled(release): current = schema.load(gh.file(core, heads[core], api['schema'])) idle, types = schema.coverage(current, api['surface'], schema.check(current, ops)[2], api['namespaces']) + held = upstream.source(cfg, 'contracts') + pinned = {held['branch']: heads[held['repo']]} + try: + refs = upstream.release_refs(gh, held, local['floor']) + styles, unmatched = upstream.stylesheets(gh, held, refs, local['styled'], pinned) + compat = {'refs': refs, 'contracts': upstream.contracts(gh, held, refs, pinned), 'styles': styles, 'unmatched': unmatched} + except GitHubError as e: + # These sections only report: a failed read leaves them out and says so, and the news still goes out + compat = {'refs': [], 'contracts': [], 'styles': {}, 'unread': str(e)} return {'releases': (newest, stable, latest), 'stages': stages, 'matrix': matrix, 'unstated': unstated, - 'idle': idle, 'types': types, 'legacy': sorted(watched[tagged].items())} + 'idle': idle, 'types': types, **compat, + # Stylesheets are not pages to move off: they are what the plugin's own CSS sits on + 'legacy': [(path, why) for path, why in sorted(watched[tagged].items()) if not path.endswith('.css')]} diff --git a/.github/unraid-watch/test_commands.py b/.github/unraid-watch/test_commands.py index afc99793..fab44c34 100644 --- a/.github/unraid-watch/test_commands.py +++ b/.github/unraid-watch/test_commands.py @@ -5,7 +5,7 @@ import watch from github import GitHubError -from world import API, CFG, DOCS, ME, NEW, RELEASE, SCRIPT, SDL, USERPREFS, WEB, WITHOUT_STOP, Case, World, sha, url +from world import API, CFG, DOCS, EVENTS, ME, NEW, RELEASE, SCRIPT, SDL, STYLES, USERPREFS, WEB, WITHOUT_STOP, Case, World, sha, url class ContractTest(Case): @@ -77,10 +77,59 @@ def test_scan_problem_fails_the_contract(self): self.assertEqual(code, 1) self.assertIn('::error::a.js:6:', out) + def test_contracts_are_checked_on_master_and_listed(self): + code, out = self.contract() + self.assertEqual(code, 0) + self.assertIn(f'- contract {EVENTS}: holds on 2 of 2 refs', out) + + def test_a_contract_a_supported_release_breaks_fails_and_names_the_release(self): + self.w.release_line() + self.w.tree(WEB, '9.0.3', {EVENTS: 'ev0'}) + self.w.blob(WEB, 'ev0', "$arrResponse = ['ok' => $DockerClient->startContainer($container)];\n") + code, out = self.contract() + self.assertEqual(code, 1) + self.assertIn(f"::error::unraid/webgui: {EVENTS} does not match \"'success' => \" on 9.0.3: answers in `success`", out) + self.assertIn(f'- contract {EVENTS}: holds on 1 of 2 refs', out) + + def test_a_contract_file_a_release_does_not_have_is_named_missing_not_mismatched(self): + self.w.release_line() + self.w.tree(WEB, '9.0.3', {}) + code, out = self.contract() + self.assertEqual(code, 1) + self.assertIn(f'::error::unraid/webgui: {EVENTS} is missing on 9.0.3: answers in `success`', out) + self.assertNotIn('does not match', out) + + def test_a_release_before_a_contracts_since_is_not_held_to_it(self): + self.w.release_line() + self.w.tree(WEB, '9.0.3', {}) + cfg = {**CFG, 'sources': [{**s, 'contracts': [{**s['contracts'][0], 'since': '9.1.0'}]} if 'contracts' in s else s + for s in CFG['sources']]} + code, out = self.captured(watch.cmd_contract, cfg, self.w.client(), self.w.root, None) + self.assertEqual(code, 0) + self.assertIn(f'- contract {EVENTS}: holds on 1 of 1 refs', out) + + def test_only_stable_releases_from_the_plugins_minimum_are_read(self): + self.w.release_line() + self.contract() + read = {c[1].split('/git/trees/')[1].split('?')[0] for c in self.w.fake.calls if f'/repos/{WEB}/git/trees/' in c[1]} + # master is read at the sha the run pinned it to, not by its moving name + self.assertEqual(read, {'9.0.3', NEW[WEB]}) + + def test_a_manifest_without_a_minimum_stops_the_contract_before_any_request(self): + world = World(self, manifest='\n') + with self.assertRaisesRegex(watch.Problem, 'no min="x.y.z"'): + self.contract(world=world) + self.assertEqual(world.fake.calls, []) + + def test_no_supported_release_tag_is_an_error_not_a_pass_on_master_alone(self): + self.w.tags(WEB, ['8.9.0', '9.1.0-beta.2', '2030.11.10']) + with self.assertRaisesRegex(GitHubError, 'no stable release tag at or after 9.0.0'): + self.contract() + class CheckTest(Case): - def check(self, script): - world = World(self, script) + def check(self, script, **world): + world = World(self, script, **world) code, out = self.captured(watch.cmd_check, CFG, world.root) self.assertEqual(world.fake.calls, []) return code, out @@ -107,6 +156,45 @@ def test_plugin_that_references_no_endpoint_fails(self): self.assertEqual(code, 1) self.assertIn('::error::unraid/webgui: the plugin references none of its endpoints', out) + def test_an_unraid_css_variable_without_a_fallback_fails(self): + code, out = self.check(SCRIPT, styles=STYLES + '.tip { margin: var(--gap); }\n') + self.assertEqual(code, 1) + self.assertIn('::error::a.css:3: var(--gap) has no fallback and FolderView3 does not define --gap', out) + + def test_a_manifest_without_a_minimum_fails(self): + code, out = self.check(SCRIPT, manifest='\n') + self.assertEqual(code, 1) + self.assertIn('::error::plugin.plg: no min="x.y.z" on its PLUGIN tag', out) + + def test_a_missing_manifest_says_it_is_missing(self): + world = World(self) + Path(world.root, 'plugin.plg').unlink() + code, out = self.captured(watch.cmd_check, CFG, world.root) + self.assertEqual(code, 1) + self.assertIn('::error::plugin.plg is missing', out) + + def test_a_plugin_with_no_stylesheets_fails_instead_of_reading_as_nothing_styled(self): + world = World(self) + Path(world.root, 'plugin/styles/a.css').unlink() + code, out = self.captured(watch.cmd_check, CFG, world.root) + self.assertEqual(code, 1) + self.assertIn('::error::plugin/styles has no stylesheets that style an element', out) + + def test_release_checks_with_nothing_to_check_fail_instead_of_passing(self): + web = next(s for s in CFG['sources'] if 'contracts' in s) + for broken in ({**web, 'contracts': []}, {**web, 'styles': {**web['styles'], 'themes': []}}, + {**web, 'contracts': [{'path': EVENTS, 'match': '(', 'why': 'w'}]}, {**web, 'contracts': [{'path': EVENTS}]}): + with self.subTest(broken=broken.get('contracts')): + cfg = {**CFG, 'sources': [broken if s is web else s for s in CFG['sources']]} + code, out = self.captured(watch.cmd_check, cfg, World(self).root) + self.assertEqual(code, 1) + self.assertIn('::error::watch.json: ', out) + + def test_an_empty_stylesheet_fails_the_same_way(self): + code, out = self.check(SCRIPT, styles='') + self.assertEqual(code, 1) + self.assertIn('::error::plugin/styles has no stylesheets that style an element', out) + class MainTest(Case): def main(self, *argv): diff --git a/.github/unraid-watch/test_css.py b/.github/unraid-watch/test_css.py new file mode 100644 index 00000000..b1455670 --- /dev/null +++ b/.github/unraid-watch/test_css.py @@ -0,0 +1,135 @@ +import tempfile +import unittest +from pathlib import Path + +import css + + +class RulesTest(unittest.TestCase): + def test_each_selector_gets_the_declarations_and_its_at_rule(self): + text = '/* a\ncomment */ @media (max-width: 9px) { .a, #b > .c { white-space: pre-line; margin-top:4px!important } }\n.d{display:none}' + self.assertEqual(css.rules(text), [ + ('@media (max-width: 9px)', '.a', {'white-space': 'pre-line', 'margin-top': '4px !important'}), + ('@media (max-width: 9px)', '#b > .c', {'white-space': 'pre-line', 'margin-top': '4px !important'}), + ('', '.d', {'display': 'none'})]) + + def test_nested_rules_resolve_against_their_parent_and_keep_its_own_declarations(self): + text = '.title { display: flex; &:first-of-type { margin-top: 0 } .x, &.y { top: 1px } @media (min-width: 1px) { clear: both } }' + self.assertEqual(css.rules(text), [ + ('', '.title', {'display': 'flex'}), + ('', '.title:first-of-type', {'margin-top': '0'}), + ('', '.title .x', {'top': '1px'}), + ('', '.title.y', {'top': '1px'}), + ('@media (min-width: 1px)', '.title', {'clear': 'both'})]) + + def test_a_declaration_after_a_nested_rule_wins_as_it_does_in_the_browser(self): + self.assertEqual(css.merged(['.tip { & { top: 1px; } top: 2px; }']), {('', '.tip', 'top'): '2px'}) + + def test_a_statement_at_rule_does_not_swallow_the_next_rule_and_keyframes_are_no_elements(self): + text = '@charset "UTF-8";\n@import url(a.css);\n.tip { display: block }\n@keyframes k { from { top: 0 } }' + self.assertEqual(css.rules(text), [('', '.tip', {'display': 'block'})]) + + def test_a_brace_inside_a_string_is_just_text(self): + self.assertEqual(css.rules('.q::after { content: "}"; } .row { top: 0 }'), + [('', '.q::after', {'content': '"}"'}), ('', '.row', {'top': '0'})]) + + def test_spacing_and_attribute_quotes_do_not_make_a_rule_new(self): + a = css.merged(['label+.content{top:0} [type="radio"]~.x{top:0} @media (max-width:9px){.y{top:0}}']) + b = css.merged(['label + .content { top: 0 } [type=radio] ~ .x { top: 0 } @media ( max-width: 9px ) { .y { top: 0 } }']) + self.assertEqual(a, b) + self.assertIn(('@media (max-width: 9px)', '.y', 'top'), a) + + def test_a_guard_nested_in_where_and_not_leaves_the_element_it_styles(self): + self.assertEqual(css.subject('a.button:where(:not(.ext *))'), ['.button']) + self.assertEqual(css.subject('.box:where(:not(:is(.a .b) .c))'), ['.box']) + + def test_a_generated_box_or_an_attribute_value_is_not_the_element(self): + self.assertEqual(css.subject('.tip::before'), []) + self.assertEqual(css.subject('a[href$=".png"]'), []) + + def test_a_group_rule_with_no_space_after_its_keyword_is_still_read(self): + self.assertEqual(css.rules('@media(max-width:600px){.tip{white-space:pre-line}} @supports(display:grid){.row{top:0}}'), + [('@media (max-width: 600px)', '.tip', {'white-space': 'pre-line'}), ('@supports (display: grid)', '.row', {'top': '0'})]) + + def test_a_comma_inside_not_stays_in_its_selector(self): + self.assertEqual(css.rules('.x:not(.p, .q), .z { display: none }'), + [('', '.x:not(.p, .q)', {'display': 'none'}), ('', '.z', {'display': 'none'})]) + + def test_a_semicolon_inside_a_url_does_not_end_the_declaration(self): + self.assertEqual(css.rules('.a { background: url(data:image/png;base64,xy); top: 0 }'), + [('', '.a', {'background': 'url(data:image/png;base64,xy)', 'top': '0'})]) + + def test_the_styled_element_is_the_last_compound_without_what_not_names(self): + self.assertEqual(css.subject('#docker_containers > tr.sortable:not(.folder)'), ['.sortable']) + self.assertEqual(css.subject('div.title:first-of-type'), ['.title']) + self.assertEqual(css.subject('label + .content'), ['.content']) + + +class ChangesTest(unittest.TestCase): + OURS = {'.tip': {('', 'color')}, '.row': {('', 'white-space')}} + + def by_ref(self, old, new): + return {'9.0.0': css.merged([old]), 'master': css.merged([new])} + + def test_a_layout_property_unraid_changed_on_an_element_the_plugin_styles_is_listed(self): + rows = css.changes(self.by_ref('.tip { display: block }', '.tip { white-space: pre-line }'), ['9.0.0', 'master'], self.OURS) + self.assertEqual(rows, [('', '.tip', 'display', [('9.0.0', 'block'), ('master', None)]), + ('', '.tip', 'white-space', [('9.0.0', None), ('master', 'pre-line')])]) + + def test_what_the_plugin_sets_itself_colours_and_elements_it_does_not_style_are_left_out(self): + # .row's colour: an element the plugin styles, a property it does not set, but a colour, not layout + old = '.row { white-space: nowrap; color: red } .tip { color: red } .other { display: block }' + new = '.row { white-space: normal; color: blue } .tip { color: blue } .other { display: flex }' + self.assertEqual(css.changes(self.by_ref(old, new), ['9.0.0', 'master'], self.OURS), []) + + def test_a_later_stylesheet_wins_as_the_page_loads_them(self): + self.assertEqual(css.merged(['.tip { top: 1px }', '.tip { top: 2px }']), {('', '.tip', 'top'): '2px'}) + + def test_an_important_declaration_is_not_overwritten_by_a_plain_one(self): + self.assertEqual(css.merged(['.tip { top: 1px !important }', '.tip { top: 2px }']), {('', '.tip', 'top'): '1px !important'}) + self.assertEqual(css.rules('.tip { top: 1px !important; top: 2px }'), [('', '.tip', {'top': '1px !important'})]) + self.assertEqual(css.merged(['.tip { top: 1px !important }', '.tip { top: 3px !important }']), {('', '.tip', 'top'): '3px !important'}) + + def test_the_plugin_setting_a_property_under_a_condition_covers_only_that_condition(self): + ours = css.styled(['@media (max-width: 600px) { .tip { white-space: normal } }']) + by_ref = {'9.0.0': css.merged(['.tip { white-space: nowrap }']), 'master': css.merged(['.tip { white-space: pre-line }'])} + self.assertEqual([r[2] for r in css.changes(by_ref, ['9.0.0', 'master'], ours)], ['white-space']) + same = {'9.0.0': css.merged(['@media (max-width: 600px) { .tip { white-space: nowrap } }']), + 'master': css.merged(['@media (max-width: 600px) { .tip { white-space: pre-line } }'])} + self.assertEqual(css.changes(same, ['9.0.0', 'master'], ours), []) + + +class FallbacksTest(unittest.TestCase): + def check(self, sheet, code=''): + tmp = tempfile.TemporaryDirectory() + self.addCleanup(tmp.cleanup) + a, js = Path(tmp.name, 'a.css'), Path(tmp.name, 'a.js') + a.write_text(sheet, encoding='utf-8') + js.write_text(code, encoding='utf-8') + return css.fallbacks([a], [js]) + + def test_an_unraid_variable_without_a_fallback_is_named_with_its_line(self): + (problem,) = self.check('/* two\nlines */\n.a { color: var(--text); }\n') + self.assertTrue(problem.startswith('a.css:3: var(--text) has no fallback and FolderView3 does not define --text'), problem) + + def test_a_fallback_or_a_variable_the_plugin_owns_passes(self): + self.assertEqual(self.check('.a { color: var(--text, #fff); }'), []) + self.assertEqual(self.check(':root { --gap: 5px; } .a { gap: var(--gap); }'), []) + self.assertEqual(self.check('.a { color: var(--fv3-name-color); }', "const vars = { 'fv3-name-color': '#fff' };"), []) + self.assertEqual(self.check('.a { color: var(--graph-cpu); }', "$vars = ['graph-cpu' => '#2b8da3'];"), []) + + def test_a_word_the_code_merely_uses_does_not_make_an_unraid_variable_the_plugins(self): + (problem,) = self.check('.a { color: var(--text); }', "fields.push({ type: 'text', label: 'Name' });") + self.assertIn('var(--text) has no fallback', problem) + + def test_code_that_only_reads_a_variable_does_not_define_it(self): + (problem,) = self.check('.a { color: var(--text); }', "getComputedStyle(document.body).getPropertyValue('--text');") + self.assertIn('var(--text) has no fallback', problem) + + def test_a_variable_nested_in_a_fallback_needs_its_own(self): + (problem,) = self.check('.a { color: var(--fv3-x, var(--text)); }', "'fv3-x'") + self.assertIn('var(--text) has no fallback', problem) + + +if __name__ == '__main__': + unittest.main() diff --git a/.github/unraid-watch/test_github.py b/.github/unraid-watch/test_github.py index dbe3043c..bdcf981c 100644 --- a/.github/unraid-watch/test_github.py +++ b/.github/unraid-watch/test_github.py @@ -15,6 +15,16 @@ def compare(self, page, status, total, numbers): self.fake.routes['GET', url(f'/repos/o/r/compare/{sha(1)}...{sha(2)}', page=page, per_page=100)] = { 'status': status, 'total_commits': total, 'commits': [commit(n) for n in numbers]} + def test_tags_follow_every_page(self): + self.fake.routes['GET', url('/repos/o/r/tags', page=1, per_page=100)] = [{'name': f't{n}'} for n in range(100)] + self.fake.routes['GET', url('/repos/o/r/tags', page=2, per_page=100)] = [{'name': 't100'}] + self.assertEqual(self.gh.tags('o/r'), [f't{n}' for n in range(101)]) + + def test_a_blob_is_read_once_however_many_releases_share_it(self): + self.fake.routes['GET', '/repos/o/r/git/blobs/abc'] = '.tip { top: 0 }' + self.assertEqual([self.gh.blob('o/r', 'abc') for _ in range(3)], ['.tip { top: 0 }'] * 3) + self.assertEqual(len(self.fake.sent('GET')), 1) + def test_between_follows_every_page(self): self.compare(1, 'ahead', 105, range(100, 200)) self.compare(2, 'ahead', 105, range(200, 205)) diff --git a/.github/unraid-watch/test_releases.py b/.github/unraid-watch/test_releases.py index d24901b5..8146c8b4 100644 --- a/.github/unraid-watch/test_releases.py +++ b/.github/unraid-watch/test_releases.py @@ -10,6 +10,9 @@ def test_versions_sort_beta_before_rc_before_final(self): ['9.0.9', '9.0.10', '9.1.0-beta.2', '9.1.0-beta.2.1', '9.1.0-beta.10', '9.1.0-rc.1', '9.1.0', '10.0.0-beta.1']) + def test_an_os_release_tag_is_a_stable_version_not_a_date(self): + self.assertEqual([t for t in ('9.4.0', '9.4.0-rc.1', '2030.11.10', 'v9.4.0', '9.4') if releases.os_tag(t)], ['9.4.0']) + def test_stable_means_no_prerelease_suffix(self): self.assertTrue(releases.stable('9.1.0')) self.assertFalse(releases.stable('9.1.0-rc.1')) diff --git a/.github/unraid-watch/test_report.py b/.github/unraid-watch/test_report.py index 4b01e673..a3c627de 100644 --- a/.github/unraid-watch/test_report.py +++ b/.github/unraid-watch/test_report.py @@ -181,5 +181,11 @@ def test_unexpected_comment_link_is_refused(self): report.announce(data, link) +class RunsTest(unittest.TestCase): + def test_releases_with_the_same_value_read_as_one_span(self): + values = [('9.0.0', None), ('9.1.0', None), ('9.2.0', '4px'), ('9.3.0', None), ('master', None)] + self.assertEqual(report._runs(values), 'not set in `9.0.0`–`9.1.0`, `4px` in `9.2.0`, not set in `9.3.0`–`master`') + + if __name__ == '__main__': unittest.main() diff --git a/.github/unraid-watch/test_status.py b/.github/unraid-watch/test_status.py index 8c97d6e3..d4ef3ff2 100644 --- a/.github/unraid-watch/test_status.py +++ b/.github/unraid-watch/test_status.py @@ -4,7 +4,7 @@ import status import upstream import watch -from world import (API, BETA_API, BETA_WEB, CFG, DOCS, LATEST_API, ME, NEW, RELEASE, SCRIPT, STABLE_WEB, USERPREFS, WEB, +from world import (API, BETA_API, BETA_WEB, CFG, DOCS, EVENTS, LATEST_API, ME, NEW, RELEASE, SCRIPT, STABLE_WEB, USERPREFS, WEB, Case, World, commit, sha, url) OPS = [('{ docker { statuses { name } } }', ['a.js:3']), @@ -42,7 +42,7 @@ def view(self): self.w.release_line() return status.gather(self.w.client(), CFG, OPS, {API: {'api/switch.ts': 'page switch'}, WEB: {'emhttp/page/': 'markup', USERPREFS: 'called from a.js:5'}, - DOCS: {}}, NEW) + DOCS: {}}, NEW, self.local()) def test_stages_cover_merged_released_and_the_prerelease(self): titles = [title for title, _ in self.view()['stages']] @@ -98,6 +98,25 @@ def test_status_reads_as_expected(self): '', '', '', + '**Contracts by OS release**', + '', + 'What FolderView3 relies on in the webgui, checked on its release tags `9.0.3` and on `master`.', + '', + '- `Events.php` answers in `success`: holds on all 2', + '', + '**Unraid CSS by OS release**', + '', + 'Layout properties Unraid sets on elements FolderView3 styles, that differ between releases, and that FolderView3 ' + 'does not set itself.', + '', + '- `.tip` `white-space`: not set in `9.0.3`, `pre-line` in `master`', + '', + '
No longer set in the stylesheets read here (1; may have moved elsewhere)', + '', + '- `.tip` `display`: `block` in `9.0.3`, not set in `master` (azure)', + '', + '
', + '', report.STATUS, ])) @@ -108,7 +127,7 @@ def test_each_schema_is_fetched_once_however_many_stages_use_it(self): url(f'/repos/{API}/contents/api/schema.graphql', ref=ref) for ref in (RELEASE, BETA_API, LATEST_API, NEW[API]))) def test_with_no_release_notes_the_stages_that_need_them_say_so(self): - body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW)) + body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW, self.local())) self.assertIn('Latest API release `v4.0.0`.', body) self.assertIn('**Coming: merged, in no release**\n\n- unraid/api `v4.0.0`...`main`: nothing\n' '- unraid/webgui `not stated`...`master`: not available\n', body) @@ -121,7 +140,7 @@ def test_with_no_release_notes_the_stages_that_need_them_say_so(self): def test_release_whose_notes_do_not_state_the_api_says_so(self): self.w.release_line() self.w.notes(NEW[DOCS], {'9.1.0.md': '# Version 9.1.0-beta.2 2030-01-02\n\nNothing about the API.\n'}) - body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW)) + body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW, self.local())) self.assertIn('Newest OS release `9.1.0-beta.2` (API `not stated`), latest API release `v4.2.0`.', body) self.assertIn('**Coming: released API, not in an OS build**\n\n- unraid/api `not stated`...`v4.2.0`: not available\n', body) self.assertIn('- API version not stated in the notes: `9.1.0-beta.2`', body) @@ -129,11 +148,42 @@ def test_release_whose_notes_do_not_state_the_api_says_so(self): def test_release_documented_before_its_tag_exists_is_shown_as_not_available(self): self.w.release_line() del self.w.fake.routes['GET', f'/repos/{WEB}/commits/9.1.0-beta.2'] - body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW)) + body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW, self.local())) self.assertIn('- unraid/webgui `9.1.0-beta.2`...`master`: not available\n', body) self.assertIn('- unraid/webgui `9.0.3`...`9.1.0-beta.2`: not available\n', body) self.assertIn('- unraid/api `v4.0.0`...`v4.1.0`:\n - removed', body) + def test_a_failed_read_leaves_the_release_checks_out_and_says_so(self): + self.w.fake.routes['GET', url(f'/repos/{WEB}/tags', page=1, per_page=100)] = (500, 'boom') + body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW, self.local())) + self.assertIn('**Operations by OS release**', body) + self.assertIn('**Contracts and Unraid CSS by OS release**: could not be read (`GET /repos/unraid/webgui/tags: HTTP 500', body) + self.assertNotIn('**Unraid CSS by OS release**', body) + + def test_a_listed_stylesheet_no_release_has_is_named(self): + cfg = {**CFG, 'sources': [{**s, 'styles': {**s['styles'], 'files': s['styles']['files'] + ['css/typo-{theme}.css']}} + if 'styles' in s else s for s in CFG['sources']]} + self.w.release_line() + body = report.render_status(status.gather(self.w.client(), cfg, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW, self.local())) + self.assertIn('Listed in watch.json but on no release: `css/typo-azure.css`, `css/typo-black.css`.', body) + + def test_an_empty_stylesheet_counts_as_missing_not_as_no_change(self): + self.w.release_line() + self.w.blob(WEB, 'old0', ' \n') + body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW, self.local())) + self.assertIn('Listed in watch.json but on no release: `css/old-black.css`.', body) + + def test_one_themes_file_missing_on_every_release_is_named_though_another_theme_has_it(self): + self.w.release_line() + self.w.tree(WEB, '9.0.3', {EVENTS: 'ev1', 'css/old-azure.css': 'old1'}) + body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW, self.local())) + self.assertIn('Listed in watch.json but on no release: `css/old-black.css`.', body) + + def test_watched_stylesheets_are_not_listed_as_legacy_pages(self): + view = status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {'css/azure.css': 'theme', USERPREFS: 'prefs'}, DOCS: {}}, + NEW, self.local()) + self.assertEqual(view['legacy'], [(USERPREFS, 'prefs')]) + def test_file_that_differs_with_no_commit_to_show_just_says_differs(self): view = self.view() view['stages'] = [('Coming: merged, in no release', [(API, 'v4.2.0', 'main', [], [('api/switch.ts', 'w', [])])])] @@ -143,7 +193,7 @@ def test_when_the_newest_release_is_stable_there_is_no_prerelease_stage(self): self.w.release_line() self.w.notes(NEW[DOCS], {'9.0.3.md': '# Version 9.0.3 2030-01-01\n\n* The Unraid API version remains 4.0.0.\n'}) self.w.tree(WEB, STABLE_WEB, {'emhttp/page': 't1', USERPREFS: 'u0'}) - body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW)) + body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW, self.local())) self.assertIn('Newest OS release `9.0.3` (API `4.0.0`), latest API release `v4.2.0`.', body) self.assertNotIn('Coming with', body) self.assertIn('- unraid/webgui `9.0.3`...`master`: nothing', body) @@ -152,7 +202,7 @@ def test_when_the_newest_release_is_stable_there_is_no_prerelease_stage(self): def test_latest_release_that_an_os_build_already_ships_is_one_row(self): self.w.release_line() self.w.fake.routes['GET', f'/repos/{API}/releases/latest'] = {'tag_name': 'v4.1.0'} - body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW)) + body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {}, WEB: {}, DOCS: {}}, NEW, self.local())) self.assertIn('`v4.1.0` (latest API release, Unraid 9.1.0-beta.2)', body) self.assertIn('- unraid/api `v4.1.0`...`v4.1.0`: nothing', body) @@ -161,7 +211,7 @@ def test_upstream_text_in_the_status_stays_inert(self): self.w.between(API, [50, 51], span=(LATEST_API, NEW[API])) self.w.fake.routes['GET', url(f'/repos/{API}/commits', page=1, path='api/switch.ts', per_page=100, sha=NEW[API])] = [ commit(51, 'x `y` @someone '), commit(50, 'older')] - body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {'api/switch.ts': 'w'}, WEB: {}, DOCS: {}}, NEW)) + body = report.render_status(status.gather(self.w.client(), CFG, OPS, {API: {'api/switch.ts': 'w'}, WEB: {}, DOCS: {}}, NEW, self.local())) self.assertIn("`api/switch.ts`: 2 commits, newest `2026-10-01 x 'y' @someone `", body) self.assertTrue(body.endswith('\n\n' + report.STATUS)) @@ -213,6 +263,14 @@ def test_refreshed_even_when_news_was_posted(self): self.w.run() self.assertEqual((len(self.w.posted), len(self.w.status)), (1, 1)) + def test_news_still_goes_out_when_the_release_checks_cannot_be_read(self): + self.w.state() + self.w.hit() + self.w.fake.routes['GET', f'/repos/{WEB}/git/blobs/ev1'] = (500, 'boom') + code, _ = self.w.run() + self.assertEqual((code, len(self.w.posted), len(self.w.status)), (0, 1, 1)) + self.assertIn('could not be read', self.w.status[0][1]) + def test_status_command_prints_and_writes_nothing(self): code, out = self.captured(watch.cmd_status, CFG, self.w.client(), self.w.root) self.assertEqual(code, 0) diff --git a/.github/unraid-watch/upstream.py b/.github/unraid-watch/upstream.py index f482815f..bca34aa6 100644 --- a/.github/unraid-watch/upstream.py +++ b/.github/unraid-watch/upstream.py @@ -1,8 +1,10 @@ """What upstream looks like, read through the GitHub client: schema changes, release notes, file differences.""" import re +import css import releases import schema +from github import GitHubError NOTES = re.compile(r'[\w.-]+\.md\Z') @@ -67,6 +69,59 @@ def validity(gh, src, ops, refs): return out +def release_refs(gh, src, floor): + """Stable release tags at or after floor (the plugin's declared minimum), oldest first, then the development branch.""" + tags = [t for t in gh.tags(src['repo']) if releases.os_tag(t) and releases.order(t) >= releases.order(floor)] + # None would leave only the development branch checked, read as every release passing + if not tags: + raise GitHubError(f'{src["repo"]}: no stable release tag at or after {floor}') + return sorted(tags, key=releases.order) + [src['branch']] + + +def text_at(gh, repo, ref, path): + """A file's text at a ref; None when the file is not there.""" + blob = gh.tree(repo, ref).get(path) + return None if blob is None else gh.blob(repo, blob) + + +def applies(entry, ref): + """A contract with `since` holds only from that release on; the development branch is always held to it.""" + return 'since' not in entry or not releases.VERSION.fullmatch(ref) or releases.order(ref) >= releases.order(entry['since']) + + +def contracts(gh, src, refs, pinned): + """[(contract, {ref: True, False, 'missing' (no such file), or None where it does not apply})]; pinned maps a branch to its sha.""" + out = [] + for entry in src.get('contracts', []): + found = {} + for ref in refs: + text = text_at(gh, src['repo'], pinned.get(ref, ref), entry['path']) if applies(entry, ref) else None + found[ref] = None if not applies(entry, ref) else 'missing' if text is None else bool(re.search(entry['match'], text)) + out.append((entry, found)) + return out + + +def stylesheets(gh, src, refs, ours, pinned): + """({theme: css.changes}, [listed file no release has]) for Unraid's stylesheets; a file one release lacks is skipped.""" + styles = src['styles'] + out, seen = {}, set() + # Each theme's own file is its own input: one theme's themes/{theme}.css does not stand in for another's + listed = list(dict.fromkeys(p.format(theme=t) for t in styles['themes'] for p in styles['files'])) + for theme in styles['themes']: + by_ref = {} + for ref in refs: + texts = [] + for path in (p.format(theme=theme) for p in styles['files']): + text = text_at(gh, src['repo'], pinned.get(ref, ref), path) + # An empty file is no input either: a theme of empty files must not read as "no change" + if text and text.strip(): + texts.append(text) + seen.add(path) + by_ref[ref] = css.merged(texts) + out[theme] = css.changes(by_ref, refs, ours) + return out, [p for p in listed if p not in seen] + + def differences(gh, repo, paths, start, head): """[(path, why, commits)] for watched paths that differ between two commits; commits is None when start is no ancestor.""" a, b = gh.tree(repo, start), gh.tree(repo, head) diff --git a/.github/unraid-watch/watch.json b/.github/unraid-watch/watch.json index 6c15eb26..fb35d8c5 100644 --- a/.github/unraid-watch/watch.json +++ b/.github/unraid-watch/watch.json @@ -1,6 +1,7 @@ { "issue": 52, "plugin": "src/folder.view3/usr/local/emhttp/plugins/folder.view3", + "manifest": "folder.view3.plg", "expand": [ {"match": "docker { ${gqlAction}", "map": "fv3DockerActionMap"}, {"match": "vm { ${gqlAction}", "map": "fv3VmActionMap"} @@ -48,7 +49,36 @@ "emhttp/plugins/dynamix/include/DefaultPageLayout/BodyInlineJS.php": "task tray openDocker runs through from 7.4", "emhttp/plugins/dynamix/include/TaskCommand.php": "task tray endpoint behind openDocker from 7.4", "emhttp/plugins/dynamix/styles/default-dynamix.css": "tooltipster rules the advanced preview popup is drawn inside (7.4 added white-space: pre-line)", - "emhttp/plugins/dynamix/styles/default-base.css": "sweet-alert, table and menu rules the plugin's dialogs and rows sit in" + "emhttp/plugins/dynamix/styles/default-base.css": "sweet-alert, table and menu rules the plugin's dialogs and rows sit in", + "emhttp/plugins/dynamix/styles/default-color-palette.css": "colour variables the plugin's CSS reads, each with its own fallback", + "emhttp/plugins/dynamix/styles/themes/azure.css": "azure theme rules under the folder rows and dialogs", + "emhttp/plugins/dynamix/styles/themes/black.css": "black theme rules under the folder rows and dialogs", + "emhttp/plugins/dynamix/styles/themes/gray.css": "gray theme rules under the folder rows and dialogs", + "emhttp/plugins/dynamix/styles/themes/white.css": "white theme rules under the folder rows and dialogs", + "emhttp/plugins/dynamix.docker.manager/sheets/DockerContainers.css": "Docker tab rows the folders sit among", + "emhttp/plugins/dynamix.vm.manager/sheets/VMMachines.css": "VMs tab rows the folders sit among", + "emhttp/plugins/dynamix.vm.manager/styles/dynamix.vm.manager.css": "VM list rules the VM folders inherit", + "emhttp/plugins/dynamix/sheets/DashStats.css": "Dashboard tiles the folder tiles are drawn in", + "emhttp/plugins/dynamix.docker.manager/include/Events.php": "answers a container action: true, or the reason Unraid refused it (shared.js fv3ActionAnswer)" + }, + "contracts": [ + {"path": "emhttp/plugins/dynamix.docker.manager/include/Events.php", "match": "'success' => \\$DockerClient->startContainer\\(", + "why": "answers a container start in `success`: true, or the reason it was refused (shared.js fv3ActionAnswer)"}, + {"path": "emhttp/plugins/dynamix.vm.manager/include/VMajax.php", "match": "\\['error' => ", + "why": "answers a refused VM action in `error` (shared.js fv3ActionAnswer)"}, + {"path": "emhttp/plugins/dynamix.docker.manager/include/UserPrefs.php", "match": "\\$save\\[\\] = \\$index\\[\\$i\\+\\+\\]\\.\"=\\\\\"\"\\.\\$name\\.\"\\\\\"\"", + "why": "saves the Docker order as N=\"name\" lines, the format the plugin reads and inserts into (lib.php fv3_parse_user_prefs)"} + ], + "styles": { + "themes": ["azure", "black", "gray", "white"], + "files": [ + "emhttp/plugins/dynamix/styles/default-{theme}.css", "emhttp/plugins/dynamix/styles/dynamix-{theme}.css", + "emhttp/plugins/dynamix/styles/default-color-palette.css", "emhttp/plugins/dynamix/styles/default-base.css", + "emhttp/plugins/dynamix/styles/themes/{theme}.css", "emhttp/plugins/dynamix/styles/default-dynamix.css", + "emhttp/plugins/dynamix/styles/jquery.sweetalert.css", "emhttp/plugins/dynamix/styles/default-popup.css", + "emhttp/plugins/dynamix.docker.manager/sheets/DockerContainers.css", "emhttp/plugins/dynamix.vm.manager/styles/dynamix.vm.manager.css", + "emhttp/plugins/dynamix.vm.manager/sheets/VMMachines.css", "emhttp/plugins/dynamix/sheets/DashStats.css" + ] } }, { diff --git a/.github/unraid-watch/watch.py b/.github/unraid-watch/watch.py index 4598e11c..728944cc 100644 --- a/.github/unraid-watch/watch.py +++ b/.github/unraid-watch/watch.py @@ -3,15 +3,17 @@ import argparse import json import os +import re import sys from pathlib import Path +import css import scan import schema import status from github import GitHub, GitHubError from report import announce, code, read_state, render, render_status, restamp, status_comment -from upstream import api_changes, release_notes, source, validity +from upstream import api_changes, contracts, release_notes, release_refs, source, validity HERE = Path(__file__).resolve().parent @@ -38,9 +40,48 @@ def derive(cfg, root): for path, where in found.items(): paths.setdefault(path, f'called from {where}') watched[src['repo']] = paths + problems += release_checks_config(cfg) return ops, watched, problems +def release_checks_config(cfg): + """Problems with the contracts and styles in watch.json: an empty list would read as every release passing.""" + held = next((s for s in cfg['sources'] if 'contracts' in s), {}) + styles = held.get('styles', {}) + problems = [] if held.get('contracts') and styles.get('themes') and styles.get('files') else \ + ['watch.json: the webgui source needs contracts and styles with themes and files, or the release checks read as passing'] + for entry in held.get('contracts', []): + if not all(isinstance(entry.get(key), str) and entry[key] for key in ('path', 'match', 'why')): + problems.append(f'watch.json: a contract needs a path, a match and a why: {entry}') + continue + try: + re.compile(entry['match']) + except re.error as e: + problems.append(f'watch.json: the contract on {entry["path"]} has a match that is not a regular expression ({e})') + return problems + + +def floor(cfg, root): + """The oldest Unraid release the plugin supports, from its manifest; a Problem when it states none.""" + manifest = Path(root, cfg['manifest']) + if not manifest.is_file(): + raise Problem(f'{cfg["manifest"]} is missing, so the oldest Unraid the plugin supports is unknown') + found = scan.minimum(manifest) + if not found: + raise Problem(f'{cfg["manifest"]}: no min="x.y.z" on its PLUGIN tag, so the oldest Unraid it supports is unknown') + return found + + +def local(cfg, root): + """What the checks per release need from the plugin: the oldest Unraid it supports, and what its stylesheets style.""" + sheets = scan.stylesheets(Path(root, cfg['plugin'])) + styled = css.styled(f.read_text(encoding='utf-8') for f in sheets) + # No stylesheets, or none that styles an element by id or class, would read as "Unraid changed nothing the plugin styles" + if not styled: + raise Problem(f'{cfg["plugin"]}/styles has no stylesheets that style an element by id or class, so what the plugin styles is unknown') + return {'floor': floor(cfg, root), 'styled': styled} + + def readable(cfg, root): """(operations, watched paths), or a Problem when the plugin source cannot be read reliably.""" ops, watched, problems = derive(cfg, root) @@ -71,6 +112,12 @@ def show(text): def cmd_check(cfg, root): ops, watched, problems = derive(cfg, root) + plugin = Path(root, cfg['plugin']) + problems += css.fallbacks(scan.stylesheets(plugin), scan.code(plugin)) + try: + local(cfg, root) + except Problem as e: + problems.append(str(e)) for query, where in ops: print(f'{where[0]:22s} {query}') for repo, paths in watched.items(): @@ -84,6 +131,8 @@ def cmd_check(cfg, root): def cmd_contract(cfg, gh, root, refs): ops, watched, errors = derive(cfg, root) + # Read before the first request: a manifest that states no minimum stops the run before anything is fetched + oldest = floor(cfg, root) api = source(cfg, 'schema') lines = [] for ref, bad, deprecated in validity(gh, api, ops, refs or [api['branch'], gh.latest_release(api['repo'])]): @@ -97,6 +146,17 @@ def cmd_contract(cfg, gh, root, refs): gone = [p for p in paths if not gh.exists(repo, head, p)] errors += [f'{repo}: {p} no longer exists on {src["branch"]}; fix the call or watch.json' for p in gone] lines.append(f'- {len(paths) - len(gone)} of {len(paths)} watched paths present in {repo}') + held = source(cfg, 'contracts') + pinned = {held['branch']: gh.sha(held['repo'], held['branch'])} + for entry, found in contracts(gh, held, release_refs(gh, held, oldest), pinned): + missing = [ref for ref, ok in found.items() if ok == 'missing'] + failed = [ref for ref, ok in found.items() if ok is False] + if missing: + errors.append(f'{held["repo"]}: {entry["path"]} is missing on {", ".join(missing)}: {entry["why"]}') + if failed: + errors.append(f'{held["repo"]}: {entry["path"]} does not match {entry["match"]!r} on {", ".join(failed)}: {entry["why"]}') + lines.append(f'- contract {entry["path"]}: holds on {sum(ok is True for ok in found.values())} of ' + f'{sum(ok is not None for ok in found.values())} refs') for error in errors: annotate('error', error) print('\n'.join(lines)) @@ -107,7 +167,7 @@ def cmd_contract(cfg, gh, root, refs): def cmd_status(cfg, gh, root): ops, watched = readable(cfg, root) heads = {src['repo']: gh.sha(src['repo'], src['branch']) for src in cfg['sources']} - show(render_status(status.gather(gh, cfg, ops, watched, heads))) + show(render_status(status.gather(gh, cfg, ops, watched, heads, local(cfg, root)))) return 0 @@ -151,7 +211,7 @@ def cmd_watch(cfg, gh, root, me, base, dry_run): for ref, bad, _ in validity(gh, api, ops, [api['branch'], gh.latest_release(api['repo'])])) + '.' body = render(report, heads) show(body) - view = render_status(status.gather(gh, cfg, ops, watched, heads)) + view = render_status(status.gather(gh, cfg, ops, watched, heads, local(cfg, root))) show(view) if dry_run: return 0 diff --git a/.github/unraid-watch/world.py b/.github/unraid-watch/world.py index 535c113c..35ba1b1e 100644 --- a/.github/unraid-watch/world.py +++ b/.github/unraid-watch/world.py @@ -19,6 +19,9 @@ BOT = {'login': 'github-actions[bot]'} API, WEB, DOCS = 'unraid/api', 'unraid/webgui', 'unraid/docs' USERPREFS = 'emhttp/plugins/dynamix.docker.manager/include/UserPrefs.php' +EVENTS = 'emhttp/plugins/dynamix.docker.manager/include/Events.php' +# The plugin colours .tip and sets .row's white-space itself +STYLES = '.tip { color: var(--c, red); }\n.row { white-space: nowrap; }\n' SDL = ''' type Query { docker: Docker! } type Mutation { docker: DockerMutations! } @@ -36,12 +39,15 @@ CFG = { 'issue': 52, 'plugin': 'plugin', + 'manifest': 'plugin.plg', 'expand': [{'match': 'docker { ${act}', 'map': 'dockerMap'}], 'sources': [ {'repo': API, 'branch': 'main', 'schema': 'api/schema.graphql', 'surface': '(?i)docker', 'namespaces': ['Docker', 'DockerMutations'], 'paths': {'api/switch.ts': 'page switch'}}, {'repo': WEB, 'branch': 'master', 'paths': {'emhttp/page/': 'markup'}, - 'endpoints': {'/plugins/dynamix.docker.manager/': 'emhttp/plugins/dynamix.docker.manager/'}}, + 'endpoints': {'/plugins/dynamix.docker.manager/': 'emhttp/plugins/dynamix.docker.manager/'}, + 'contracts': [{'path': EVENTS, 'match': "'success' => ", 'why': 'answers in `success`'}], + 'styles': {'themes': ['azure', 'black'], 'files': ['css/old-{theme}.css', 'css/{theme}.css']}}, {'repo': DOCS, 'branch': 'main', 'releases': 'notes/', 'since': '9.0.0', 'tags': WEB}, ], } @@ -94,13 +100,16 @@ def sent(self, method): class World: """A plugin, its issue, and three upstream repos that moved from OLD to NEW without touching anything watched.""" - def __init__(self, case, script=SCRIPT): + def __init__(self, case, script=SCRIPT, styles=STYLES, manifest='\n'): tmp = tempfile.TemporaryDirectory() case.addCleanup(tmp.cleanup) self.root = tmp.name scripts = Path(tmp.name, 'plugin/scripts') scripts.mkdir(parents=True) (scripts / 'a.js').write_text(script, encoding='utf-8') + Path(tmp.name, 'plugin/styles').mkdir() + Path(tmp.name, 'plugin/styles/a.css').write_text(styles, encoding='utf-8') + Path(tmp.name, 'plugin.plg').write_text(manifest, encoding='utf-8') self.fake, self.comments = Fake(), [] routes = self.fake.routes routes['GET', url(f'/repos/{ME}/issues/52/comments', page=1, per_page=100)] = self.comments @@ -120,6 +129,18 @@ def __init__(self, case, script=SCRIPT): self.tree(API, ref, {'api/schema.graphql': 's1', 'api/switch.ts': 'w1'}) self.notes(OLD[DOCS], {}) self.notes(NEW[DOCS], {}) + # One supported release that matches master: contracts hold and no stylesheet differs; master is read at its pinned sha + self.tags(WEB, ['9.0.3']) + for ref in ('9.0.3', NEW[WEB]): + self.tree(WEB, ref, {EVENTS: 'ev1', 'css/azure.css': 'st1', 'css/black.css': 'st1'}) + self.blob(WEB, 'ev1', "$arrResponse = ['success' => $DockerClient->startContainer($container)];\n") + self.blob(WEB, 'st1', '.tip { white-space: pre-line; color: red; }\n.row { white-space: normal; }\n') + + def tags(self, repo, names): + self.fake.routes['GET', url(f'/repos/{repo}/tags', page=1, per_page=100)] = [{'name': n} for n in names] + + def blob(self, repo, sha, text): + self.fake.routes['GET', f'/repos/{repo}/git/blobs/{sha}'] = text def between(self, repo, numbers, status='ahead', span=None): start, head = span or (OLD[repo], NEW[repo]) @@ -159,9 +180,15 @@ def release_line(self): self.tree(API, NEW[API], {'api/schema.graphql': 's2', 'api/switch.ts': 'w1'}) self.tree(WEB, STABLE_WEB, {'emhttp/page': 't0', USERPREFS: 'u0'}) self.tree(WEB, BETA_WEB, {'emhttp/page': 't1', USERPREFS: 'u0'}) - self.tree(WEB, NEW[WEB], {'emhttp/page': 't1', USERPREFS: 'u0'}) + self.tree(WEB, NEW[WEB], {'emhttp/page': 't1', USERPREFS: 'u0', EVENTS: 'ev1', 'css/azure.css': 'st1', 'css/black.css': 'st1'}) self.between(API, [50], span=(LATEST_API, NEW[API])) self.between(WEB, [60, 61], status='diverged', span=(STABLE_WEB, BETA_WEB)) + # Only 9.0.3 is a stable OS release at or after the plugin's floor (9.0.0); 9.0.3's azure theme sets .tip's display, + # master's does not but sets its white-space + self.tags(WEB, ['9.1.0-beta.2', '9.0.3', '8.9.0', '2030.11.10']) + self.tree(WEB, '9.0.3', {EVENTS: 'ev1', 'css/old-azure.css': 'old1', 'css/old-black.css': 'old0'}) + self.blob(WEB, 'old1', '.tip { display: block; color: blue; }\n') + self.blob(WEB, 'old0', '.other { top: 0; }\n') self.fake.routes['GET', url(f'/repos/{API}/commits', page=1, path='api/switch.ts', per_page=100, sha=NEW[API])] = [commit(50, 'feat: enable the new page', '2030-01-03T00:00:00Z')] @@ -228,6 +255,9 @@ def setUp(self): def saved(self, body): return report.read_state([bot(body)])[0] + def local(self): + return watch.local(CFG, self.w.root) + def outputs(self): """Point the job outputs at a file and return its path.""" path = Path(self.w.root, 'out') diff --git a/.github/workflows/unraid-watch.yml b/.github/workflows/unraid-watch.yml index 090167d6..a69cea42 100644 --- a/.github/workflows/unraid-watch.yml +++ b/.github/workflows/unraid-watch.yml @@ -19,6 +19,8 @@ on: pull_request: paths: - 'src/**' + # its min attribute is the oldest Unraid release the contracts are checked on + - 'folder.view3.plg' - '.github/unraid-watch/**' - '.github/workflows/unraid-watch.yml' push: