From 46500cf60c913fe918d738e67ebec47ebaef1fac Mon Sep 17 00:00:00 2001 From: MendixMau Date: Tue, 17 Nov 2026 18:06:32 +0800 Subject: [PATCH] RX1: don't flag Atlas_Core's stock theme-folder import as a FILES-route risk An audit on a real 10.24 to 11.12 run read Atlas_Core's own "@import ../../../theme/web/custom-variables" as a hand-edited vendor file at FILES-route risk. The same line is Mendix's own module-template boilerplate, present identically in 46 of the app's 52 themesource modules, including modules the audit had already confirmed carried no other edits. An Atlas_Core update regenerates it every time; it's not what an update wipes. Add bin/scss_boilerplate_check.py: classifies an outward theme/web/ import as BOILERPLATE (custom-variables / exclusion-variables: stock, no route needed) or RISK (anything else: a real app edit, route it FILES same as before). Catch and pass case wired into controls/run-controls.sh. Second lesson from the same audit (RX1-2): it read HTMLSnippet as still on 3.9.9 from an archived run's decision log, but the real delivered .mpk had already migrated every instance to Events + a bridge nanoflow / native HTML element. Note added to playbooks/widgets.md: judge widget-version claims from the shipped model, not an archived decision trail. Co-Authored-By: Claude Sonnet 5 --- upgrade-toolkit/FEEDBACK.md | 17 ++++ upgrade-toolkit/bin/scss_boilerplate_check.py | 80 +++++++++++++++++++ upgrade-toolkit/controls/run-controls.sh | 7 ++ .../controls/scss_boilerplate_control.sh | 25 ++++++ upgrade-toolkit/playbooks/widgets.md | 6 +- 5 files changed, 134 insertions(+), 1 deletion(-) create mode 100755 upgrade-toolkit/bin/scss_boilerplate_check.py create mode 100755 upgrade-toolkit/controls/scss_boilerplate_control.sh diff --git a/upgrade-toolkit/FEEDBACK.md b/upgrade-toolkit/FEEDBACK.md index 1f2338e..5d94d1b 100644 --- a/upgrade-toolkit/FEEDBACK.md +++ b/upgrade-toolkit/FEEDBACK.md @@ -29,6 +29,8 @@ MET = run metrics (branch run-metrics): step timing in `state/timing.tsv` with m LAY = the layout rung (branch feat/layout-rung): why two layout regressions of the LineApp 10.24.13 to 11.12.6 React upgrade passed the gate with '0 regressions' (a vendor module's Dojo table rules halved the Task List gallery, the Static image to Image conversion mapped width unit Auto to percentage). Source: the root-cause note `~/upgrade-lab/lineapp/WHY-NOT-CAUGHT.md`; golden input `controls/fixtures/layout/` (trimmed geometry of the old app and the pre-fix new app). Rows LAY-1 to LAY-12. +RX1 = a held-modules audit on a Mendix 10.24 to 11.12 run, re-checked against the app's own delivered `.mpk` rather than its archived run folder. Rows RX1-1 and RX1-2. + PLM = the PLM ERP LAB Connect 9.24 to 10.24 run (`~/upgrade-lab/tc-apps/TOOLKIT-FEEDBACK.md`, 31 rows PLM-1 to PLM-31; PLM-RI-n in the text is the release-impact pass). Verdict: the lesson is PLM-29 and PLM-26, two silent losses (a local layout edit and unmapped new module roles) that only the screens and smoke rungs showed. RT = the remedy trial on the notification-service runs (`~/upgrade-lab/tc-apps/TOOLKIT-FEEDBACK.md` section "RT: remedy trial", 14 rows RT-1 to RT-14; evidence `notif/r1/work/REMEDY-TRIAL.md` and `notif/r2/work/REMEDY-TRIAL.md`, run ids "notif RT r1" and "notif RT r2"). The remedy cards were applied option by option; the lesson is RT-1 and RT-3 (letter order picked a pin that broke the app) and RT-8 (a prove-clean update ignored a kept dependent). @@ -743,6 +745,8 @@ Add new items at the end with status open; the next triage round gives each one | LAY-10 | Combo box widget 2.x (the replacement of the Reference, Reference set and Drop-down selectors): the input container has min-width 135px and the placeholder is in the flow, not position absolute, so theme left/top rules on `.widget-combobox-placeholder-text` misplace it and a narrow old control grows | doc | `playbooks/dojo-successors.tsv` notes of the four selector rows: placeholder position absolute, min-width 0 where the old control was narrower | playbook-combobox-placeholder-catch, playbook-lay-rows-9-columns-pass | | LAY-11 | Image widget (from Static image): the classes land on the wrapper `div.mx-image-viewer`, not on the img, so theme height and padding rules written for the img leave it overflowing | doc | Static Image row of the playbook: `.mx-image-viewer.mx-image-viewer-responsive > img, .mx-image-viewer > img {max-width:100%; max-height:100%}` (two classes, because the widget's own `.mx-image-viewer-responsive img` rule loads after the theme) | playbook-image-wrapper-catch, playbook-lay-rows-9-columns-pass | | LAY-12 | The React rule `.mx-scrollcontainer-center .mx-layoutgrid .mx-layoutgrid-fluid {padding:0}` zeroes the padding of grids that were not nested on Dojo, because React wraps the page in an extra scroll container region; HTMLSnippet 4.x also wraps in `.widget-events` with flex 1 1 auto, which takes row space | fixed | theme_clash.py kind `react-wrapper`: a padding 0 rule under `.mx-scrollcontainer-*` that targets `.mx-layoutgrid*`, in own or vendor SCSS (summary gains `, W react-wrapper` only when W > 0); the HTMLSnippet part is a playbook note (doc) | theme-clash-react-wrapper-catch, theme-clash-react-wrapper-mutant-blind, theme-clash-react-wrapper-mutant-differs, theme-clash-react-wrapper-clean-app-pass, playbook-htmlsnippet-events-catch | +| RX1-1 | An audit of a real app's held Marketplace modules read Atlas_Core's own `web/main.scss` as a hand-edited vendor file at FILES-route risk, because two of its lines (`@import "../../../theme/web/exclusion-variables"`, `@import "../../../theme/web/custom-variables"`) reach outside the module into the project's top-level `theme/` folder. The same two lines, in the same position, are present in 46 of the app's 52 themesource modules, including modules the audit itself had confirmed carried no other edits (DataWidgets, ObjectHandling): Mendix's own module-template scaffolding ships them by default. An Atlas_Core update regenerates this exact boilerplate; it is not what an update wipes. The app's real custom styling (`theme/web/custom-variables.scss`, `exclusion-variables.scss`) lives outside every themesource module and no Marketplace update ever touches it | fixed | `bin/scss_boilerplate_check.py`: given a themesource module directory, classifies every outward `@import "theme/web/"` line in its `web/main.scss` as BOILERPLATE (name is `custom-variables` or `exclusion-variables`: stock Mendix scaffolding, no FILES route) or RISK (any other name: an app edit, route it with editroute.py FILES same as before) | scss-boilerplate-pass (only the two stock imports: 0 risk), scss-boilerplate-app-edit-risk-catch (a third outward import of app content: 1 risk, FILES route named) | +| RX1-2 | The same audit worked only from an archived run's logs and decisions (no app model survived in the archive), and concluded HTMLSnippet was still on 3.9.9, not migrated to 4.0.0. The real delivered app (pulled from its shipped `.mpk`) had already migrated every instance to the Events widget + a bridging nanoflow and to native HTMLElement; 0 classic HTMLSnippet widgets remained. An archive of decisions and logs is not proof of the shipped model: a module-version or widget-usage audit needs the delivered `.mpk` (or a model export), not the run folder, as its source of truth | doc (closed by guidance) | none (a process note, not a tool change); flagged in playbooks/widgets.md's React-client readiness checklist as a caution on HTMLSnippet-usage claims made from decision logs alone | none | Recounted from the table on 14 Oct after the QI and V3D rows (563 rows: the 542 of the night merge, which the earlier count had one closed row short, plus QI-1 to QI-10 and V3D-1 to V3D-10, plus HG-1 to HG-3 from the run history PR, 566 in all; counted by the first word of the status column). @@ -872,3 +876,16 @@ Recounted from the table on 4 Nov after LAY-1 to LAY-12 (686 rows, counted by th | backlog | 166 | | open | 0 | | total | 686 | + +Recounted from the table on 17 Nov after RX1-1 and RX1-2 (688 rows: the 686 above plus two; counted by the first word of the status column: 398 fixed, 95 doc, 14 closed, 7 won't fix, 8 unproved, 166 backlog, 0 open; RX1-1 is fixed, RX1-2 is doc, no other row changed). RX1 = a held-modules audit re-checked against the app's delivered .mpk. + +| status | count | +|---|---| +| fixed | 398 | +| doc (closed by guidance) | 95 | +| closed | 14 | +| won't fix | 7 | +| unproved | 8 | +| backlog | 166 | +| open | 0 | +| total | 688 | diff --git a/upgrade-toolkit/bin/scss_boilerplate_check.py b/upgrade-toolkit/bin/scss_boilerplate_check.py new file mode 100755 index 0000000..d9eb820 --- /dev/null +++ b/upgrade-toolkit/bin/scss_boilerplate_check.py @@ -0,0 +1,80 @@ +#!/usr/bin/env python3 +"""scss_boilerplate_check.py: is an @import that reaches outside a themesource module Mendix's own stock +boilerplate, or a real app-specific edit a FILES route must carry forward? + +Every Mendix-generated themesource//web/main.scss ships two lines by default, reaching three levels up +into the project's own top-level theme/ folder: + + @import "../../../theme/web/exclusion-variables"; + @import "../../../theme/web/custom-variables"; + +(WM1-style audits mistook these for a hand-edited vendor file at FILES-route risk on Atlas_Core: 46 of a real +app's themesource modules carried the identical line, including modules with zero other edits. An Atlas_Core +update regenerates this same boilerplate every time; it is not what an Atlas update wipes.) + +A line that reaches outside the module by the SAME depth but imports something OTHER than those two stock +names is not boilerplate: it is an app edit, and the FILES route applies (move the imported content into the +app's own design module, so the single import-path line is the only thing replayed on every update). + + scss_boilerplate_check.py [ ...] + is a themesource/ directory containing web/main.scss. + +Output: one line per outward-reaching import found: + "BOILERPLATE : stock Mendix theme-folder import, not a FILES-route risk" + "RISK : app-specific outward import, needs a FILES route (editroute.py FILES)" +then a summary: "scss_boilerplate_check: N boilerplate, M risk across K module(s)". +Exit 0 if no RISK lines found (including no outward imports at all), 1 if any RISK line was found, 2 on bad input +(a module dir with no web/main.scss). +""" +import os +import re +import sys + +STOCK_NAMES = {"custom-variables", "exclusion-variables"} +# Mendix's generated main.scss reaches out with a "../"-only relative path (any depth) into theme/web/. +OUTWARD_RE = re.compile(r'@import\s+[\'"](\.\./[\./]*theme/web/([A-Za-z0-9_-]+))[\'"]\s*;?') + + +def check_module(module_dir): + main_scss = os.path.join(module_dir, "web", "main.scss") + if not os.path.isfile(main_scss): + print(f"usage: no web/main.scss in {module_dir}", file=sys.stderr) + return None + module = os.path.basename(os.path.normpath(module_dir)) + boiler = risk = 0 + with open(main_scss, encoding="utf-8") as f: + for line in f: + m = OUTWARD_RE.search(line) + if not m: + continue + name = m.group(2) + stripped = line.strip() + if name in STOCK_NAMES: + boiler += 1 + print(f"BOILERPLATE {module} {stripped}: stock Mendix theme-folder import, not a FILES-route risk") + else: + risk += 1 + print(f"RISK {module} {stripped}: app-specific outward import, needs a FILES route (editroute.py FILES)") + return boiler, risk + + +def main(argv): + if not argv: + print("usage: scss_boilerplate_check.py [ ...]", file=sys.stderr) + return 2 + total_boiler = total_risk = 0 + modules = 0 + for module_dir in argv: + result = check_module(module_dir) + if result is None: + return 2 + b, r = result + total_boiler += b + total_risk += r + modules += 1 + print(f"scss_boilerplate_check: {total_boiler} boilerplate, {total_risk} risk across {modules} module(s)") + return 1 if total_risk else 0 + + +if __name__ == "__main__": + sys.exit(main(sys.argv[1:])) diff --git a/upgrade-toolkit/controls/run-controls.sh b/upgrade-toolkit/controls/run-controls.sh index e363325..b474012 100755 --- a/upgrade-toolkit/controls/run-controls.sh +++ b/upgrade-toolkit/controls/run-controls.sh @@ -646,6 +646,13 @@ ctl datamove-moved-pass 0 '^MOVED MendixSSO.AuthRequest.Nonce -> MendixSSO_Ext.A ctl datamove-lost-catch 1 '^LOST .*: 5 before, 3 after$' -- $DM lost ctl datamove-count-fail-catch 1 '^UNCOUNTED .*count failed after$' -- $DM fail ctl datamove-bad-plan-catch 2 "not 'Src.Entity.Attr -> Dst.Entity.Attr'" -- $DM bad +# RX1: an audit on a real app read Atlas_Core's own "../../../theme/web/custom-variables" import as a hand-edited +# vendor file at FILES-route risk; the identical line is Mendix's own module-template boilerplate (46 of the app's +# own themesource modules carried it). Only an outward import of something OTHER than those two stock names is a +# real app edit needing a FILES route. +SB="bash $B/../controls/scss_boilerplate_control.sh" +ctl scss-boilerplate-pass 0 '^BOILERPLATE mod .*exclusion-variables' '^BOILERPLATE mod .*custom-variables' '!^RISK' '^scss_boilerplate_check: 2 boilerplate, 0 risk across 1 module' -- $SB pass +ctl scss-boilerplate-app-edit-risk-catch 1 '^RISK mod .*company-brand-overrides.*needs a FILES route' '^scss_boilerplate_check: 2 boilerplate, 1 risk across 1 module' -- $SB catch # WM1 rerun 7: baseline ran microflow steps, the after walk skipped them: 4 false REGRESSIONs ctl pipeline-smoke-mf-follows-baseline-pass 0 '^--microflows$' -- bash -c "WORK=\$(mktemp -d); echo '{\"landed\": \"microflow ran\"}' > \$WORK/smoke-before.json; eval \"\$(awk '/^smoke_mf\(\)/{f=1} f{print} f&&/^}|; }\$/{exit}' \${PIPE:-$B/cloud/upgrade-pipeline.sh})\"; smoke_mf" ctl pipeline-smoke-mf-off-without-baseline-pass 0 '!microflows' -- bash -c "WORK=\$(mktemp -d); eval \"\$(awk '/^smoke_mf\(\)/{f=1} f{print} f&&/^}|; }\$/{exit}' \${PIPE:-$B/cloud/upgrade-pipeline.sh})\"; smoke_mf; echo done" diff --git a/upgrade-toolkit/controls/scss_boilerplate_control.sh b/upgrade-toolkit/controls/scss_boilerplate_control.sh new file mode 100755 index 0000000..a5c8aad --- /dev/null +++ b/upgrade-toolkit/controls/scss_boilerplate_control.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# scss_boilerplate_control.sh CASE: bin/scss_boilerplate_check.py on a fake themesource module. +# pass only the two stock Mendix theme-folder imports (no app edit) +# catch the two stock imports plus one app-specific outward import (a real FILES-route edit) +set -euo pipefail +B=$(cd "$(dirname "$0")/../bin" && pwd) +T=$(mktemp -d); trap 'rm -rf "$T"' EXIT +mkdir -p "$T/mod/web" +case "$1" in + catch) + cat > "$T/mod/web/main.scss" <<'S' +@import "../../../theme/web/exclusion-variables"; +@import "../../../theme/web/company-brand-overrides"; +@import "../../../theme/web/custom-variables"; +S + ;; + *) + cat > "$T/mod/web/main.scss" <<'S' +@import "../../../theme/web/exclusion-variables"; +@import "variables"; +@import "../../../theme/web/custom-variables"; +S + ;; +esac +python3 "$B/scss_boilerplate_check.py" "$T/mod" diff --git a/upgrade-toolkit/playbooks/widgets.md b/upgrade-toolkit/playbooks/widgets.md index bcd0fbb..d65bd2c 100644 --- a/upgrade-toolkit/playbooks/widgets.md +++ b/upgrade-toolkit/playbooks/widgets.md @@ -133,7 +133,11 @@ error 4 to 6 steps later. The "Cumulative" checkbox caption lost on the Ticket t 3. Replace, do not patch: Microflow Timer -> **Events** widget (component 224259, min Mendix 9.24, pluggable); HTMLSnippet -> HTML/JavaScript Snippet 4.x (its 4.0.0 notes: the content property must be re-entered) or HTML element; classic containers holding a pluggable widget that loads data: keep, but update the pluggable widget to - its newest version for the target. + its newest version for the target. An Events widget + a bridging nanoflow is another real migration shape for + HTMLSnippet, seen on a React-client app: 140 of 146 Events-widget instances wired to one bridge nanoflow, the rest + converted to native HTML element. Either way, judge "is HTMLSnippet still on an old version" from the shipped + `.mpk` or a live `mxcli` catalog query on it (RX1-2), not from an archived run's decision log: a decision log can + predate the fix, or the fix can land in a later rerun the log never mentions. 4. Accept as PASS* only what is proved harmless: the page content equal (shotdiff and text), no failed request, the error only on leaving the page. A teardown error is still a FAIL if the walk shows a missing value or a stuck progress bar.