bank: record the audit's backlog, and document the two shell shapes

The first run reported nine findings; four are a real backlog and five
are the audit's documented blind spot met head on.

The five: AppShell.qml keeps its page controllers in a `var` array and
refreshes the visible page with `controllers[current].refresh()`. Every
one of those five `refresh` invokables is reachable and exercised on
every page switch, and none is visible to a text scan. They are exempted
with that as their reason -- not with an issue number, because there is
nothing to fix. Rewriting AppShell into a five-armed switch so a scanner
could see the call would be bending the rung around its guard.

The four that are real -- TransactionController's `selectedAccount` and
its NOTIFY, its `posted`, and PayeeController's `paid` -- are itemised
and tracked in morph#296. `selectedAccount` looks like an actual bug:
MoveMoneyPage calls the property's WRITE and never reads it back, so the
picker cannot show a selection `refresh()` made on its own.

Neither direction of the audit reports a broken screen: no .qml file
binds a name its controller lacks.

Also record in TESTING.md and the bank README what bank taught the
guard: the context-property shell shape, the inherited-surface split,
and the fact that CI builds no part of native bank today, so this binary
runs locally only.

Closes #240 for bank -- the last of its three rungs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: Yaraslaut

examples/TESTING.md

@@ -134,18 +134,39 @@ CHECK(findings.isEmpty());
 property-bag keys inside an emitted `QVariantMap` (no metaobject exists for
 them — the per-rung "bag shape" cases remain the only guard); QML the rung
 does not own, such as the shipped `MorphForms` renderer's; dynamic member
-access; and whether the shell wires an alias to the class the test bound.
+access (`bank`'s `AppShell.qml` calls `controllers[current].refresh()`
+through a `var` array, so five reachable invokables sweep as unreferenced);
+inherited members, in the sweep direction only; and whether the shell wires
+an alias to the class the test bound.
 
 `allowUnbound(alias, member, reason)` exempts one member, with a required
 reason. The exemption list is itself audited — a member that has since been
 deleted, an alias nobody bound, or a member QML does bind is a finding — so it
 can only shrink deliberately.
 
-Adopted by `bookmarks`, `pastebin`, `polls` and `ledger`; `lims`, `kanban`
-and `bank` are tracked in morph#240. The audit's own
-mutation suite is `examples/common/testkit/test_qml_surface.cpp`: every case
-there drives it against a deliberately broken pair and asserts the specific
-finding.
+Adopted by every rung that has QML — `bookmarks`, `pastebin`, `polls`,
+`ledger`, `lims` and `kanban` — and by `examples/bank`, which is not a rung
+(morph#240). The audit's own mutation suite is
+`examples/common/testkit/test_qml_surface.cpp`: every case there drives it
+against a deliberately broken pair and asserts the specific finding.
+
+`bank` is where the two shell shapes diverge, and its adoption is worth
+reading before adding a seventh. It publishes its controllers with
+`QQmlContext::setContextProperty` rather than `setInitialProperties`, so its
+aliases are root-context names: one `bind()` per controller covers all
+thirteen files, no `bindIn()` is needed, and its `Connections` blocks name
+their target as a bare identifier (`target: app`). A bare target counts only
+when it is an alias the audit was handed — an identifier that is not is far
+more often a local `id`, and nothing distinguishes the two — so the
+unbound-bridge check does not reach this shape. `bank` also has a shared
+controller base: a reference written in QML resolves against everything the
+bridge can reach, inherited members included, while the unreferenced-member
+sweep covers only what the bound class declares itself.
+
+`bank` is not built by CI at all today (only its WebAssembly GUI is, in
+`wasm-demo.yml`), so `bank_gui_tests` — like `bank_tests` beside it — runs
+only locally, in a `-DMORPH_BUILD_BANK_EXAMPLE=ON -DMORPH_BUILD_BANK_GUI=ON`
+configure.
 
 ## The dual-mode fixture
 

examples/bank/README.md

@@ -171,6 +171,10 @@ cmake --build build --target bank_gui
 
 Structure:
 
+- **`gui/bank_gui_lib`** — a static library holding `BankClient` and every
+  controller, linking `Qt6::Core` only (no Quick, no Qml). `bank_gui` is
+  `main.cpp` plus the QML module on top of it; `bank_gui_tests` (see
+  [Tests](#tests)) is the other consumer.
 - **`gui/BankClient`** — owns the worker pool, a `morph::qt::QtExecutor`, the
   `Bridge` (local backend), DB setup, and the session. UI-toolkit-agnostic.
 - **`gui/controllers/`** — one QObject controller per domain (`AppController`,
@@ -240,6 +244,21 @@ shared on-disk test database. Notable cross-cutting tests:
 - `test_offline.cpp` — parks deposits in an `InMemoryOfflineQueue` while "offline" and
   replays them via `SyncWorker` on "reconnect".
 
+`tests/gui/` is a second binary, `bank_gui_tests`, built only when
+`-DMORPH_BUILD_BANK_GUI=ON` is also set — `bank_tests` links no Qt at all and
+is built in configures that have none. It holds `test_bank_qml_surface.cpp`,
+which points the ladder testkit's `QmlSurfaceAudit`
+(`examples/common/testkit/qml_surface.hpp`, `examples/TESTING.md`) at the six
+controllers and the thirteen `.qml` files, and fails on any name that exists on
+one side only: a renamed `Q_INVOKABLE`, a `Connections` handler for a signal
+that is gone, a property read that would resolve to `undefined`. None of those
+is a compile error or a QML warning; the pane just stays empty.
+
+```sh
+cmake --build build --target bank_gui_tests
+./build/examples/bank/bank_gui_tests
+```
+
 ## Status
 
 Models, tests, CLI, the Qt 6 GUI, and a self-contained WebAssembly build (hosted

examples/bank/tests/gui/test_bank_qml_surface.cpp

@@ -3,14 +3,43 @@
 // The QML-visible surface of all six bank GUI controllers, audited against
 // `gui/qml/` itself.
 //
-// TEMPORARY BASELINE FORM: no exemptions, so the first run prints the real
-// backlog. Replaced by the recorded form once the findings are known.
+// The bank GUI had no test of any kind before this file: `bank_tests` links
+// `bank_lib` and drives the models, and nothing linked `gui/controllers/*` at
+// all. So the thirteen `.qml` files under `gui/qml/` and the six `QObject`s
+// they bind by string have never been checked against each other. QML binds by
+// string, which means a renamed `Q_INVOKABLE`, a `Connections` handler for a
+// signal that no longer exists, or a property read resolving to `undefined` is
+// not a compile error, not a test failure, and not a QML warning — the pane
+// simply stays empty.
+//
+// This file is that check, and it is not hand-written: it points
+// `morph::ladder::testkit::QmlSurfaceAudit`
+// (`examples/common/testkit/qml_surface.hpp`) at the GUI's own QML and lets
+// those files be the expectation, in both directions. See that header for what
+// the audit does and does not cover.
+//
+// The alias mapping below is the one per-rung fact the audit cannot derive,
+// and bank's is the simplest possible shape — for a reason worth stating,
+// because it is not the shape the ladder rungs have. `gui/main.cpp` publishes
+// each controller with `QQmlContext::setContextProperty`, not
+// `setInitialProperties`: they are root-context names, visible under the same
+// name in every one of the thirteen files, and no sub-view re-exposes one
+// under a property of its own. So one `bind()` per controller covers every
+// file, and no `bindIn()` is needed — unlike ledger, whose sub-views each call
+// their own bridge plain `bridge`.
+//
+// bank is not a ladder rung (it is absent from `examples/rungs.txt` and never
+// calls `morph_add_rung()`), so this binary is wired by hand in
+// `examples/bank/CMakeLists.txt` rather than by the rung glob. It exists only
+// in a `-DMORPH_BUILD_BANK_GUI=ON -DMORPH_BUILD_TESTS=ON` configure.
 
 #include <QString>
 #include <QStringList>
 #include <catch2/catch_test_macros.hpp>
 #include <filesystem>
+#include <initializer_list>
 #include <string>
+#include <utility>
 
 #include "BankClient.hpp"
 #include "controllers/AccountController.hpp"
@@ -27,7 +56,14 @@ using morph::ladder::testkit::QmlSurfaceAudit;
 
 }  // namespace
 
-TEST_CASE("bank baseline", "[bank][gui][qml-surface]") {
+TEST_CASE("Every bank controller exposes exactly the surface gui/qml binds, and nothing more",
+          "[bank][gui][qml-surface]") {
+    // A real BankClient, because every controller holds `BridgeHandler`s
+    // constructed from one. Nothing here dispatches an action — the audit reads
+    // metaobjects and text — but `BankClient`'s constructor runs the schema
+    // migrations, so it needs a database like any other bank test does. Its own
+    // file, not the one `bank_tests` shares, so the two binaries can run
+    // concurrently.
     const auto dbPath = std::filesystem::temp_directory_path() / "morph_bank_qml_surface.db";
     bankgui::BankClient client{"DRIVER=SQLite3;Database=" + dbPath.string()};
 
@@ -46,8 +82,72 @@ TEST_CASE("bank baseline", "[bank][gui][qml-surface]") {
     audit.bind(QStringLiteral("payees"), payeeController);
     audit.bind(QStringLiteral("loans"), loanController);
 
+    // ── `refresh`, reached only through a `var` array ─────────────────────
+    // Not a backlog and not a defect: this is the audit's documented blind
+    // spot, met head on. `AppShell.qml` holds the five page controllers in
+    //
+    //     readonly property var controllers: [accounts, txns, cards, payees, loans]
+    //
+    // and refreshes the visible page with
+    // `shell.controllers[shell.current].refresh()` (AppShell.qml:12-14). That
+    // is dynamic member access — the scanner sees an index expression, never
+    // the name `refresh` against an alias — so every one of these five is
+    // reachable, exercised on every page switch, and invisible to a text scan.
+    // `app` is not in that array and has no `refresh`, which is why only five
+    // controllers appear here.
+    //
+    // Recorded rather than worked around: rewriting AppShell to a five-armed
+    // switch purely so a scanner can see the call would be bending the rung
+    // around its guard.
+    const QString dynamic = QStringLiteral(
+        "called dynamically via AppShell.qml's `controllers[current].refresh()`; "
+        "dynamic member access is outside what a text scan can see");
+    for (const char* alias : {"accounts", "txns", "cards", "payees", "loans"}) {
+        audit.allowUnbound(QString::fromLatin1(alias), QStringLiteral("refresh"), dynamic);
+    }
+
+    // ── The pre-existing backlog, recorded rather than swallowed ──────────
+    // The first run of this audit reported four members these six controllers
+    // publish that no file under gui/qml/ binds — over and above the five
+    // dynamic `refresh` calls above. The other direction was clean: no QML file
+    // binds a name its controller lacks, so no screen is broken. Each is either
+    // dead surface or a missing control, and deciding which is per-member work
+    // this file does not do. They are listed here so the guard goes live now
+    // and catches the *next* drift in either direction, with the backlog
+    // itemised instead of hidden behind a lowered bar.
+    //
+    // The list is checked in both directions too: an exemption for a member
+    // that has since been deleted, or one QML has since bound, fails this test
+    // (testkit/qml_surface.hpp). It can only shrink deliberately.
+    //
+    // Same shape as ledger's (morph#239), lims' (morph#287) and kanban's
+    // (morph#291).
+    const QString backlog = QStringLiteral("unbound controller surface, tracked in morph#296");
+    for (const auto& [alias, member] : std::initializer_list<std::pair<const char*, const char*>>{
+             // `txns.selectAccount(id)` is called, but the property it writes
+             // is never read back, so the account picker cannot reflect a
+             // selection the controller made itself (TransactionController.cpp
+             // auto-selects the first account on refresh).
+             {"txns", "selectedAccount"},
+             {"txns", "selectedChanged"},
+             // Emitted on every deposit/withdraw/transfer, and on every bill
+             // payment — no QML handles either.
+             {"txns", "posted"},
+             {"payees", "paid"},
+         }) {
+        audit.allowUnbound(QString::fromLatin1(alias), QString::fromLatin1(member), backlog);
+    }
+
     const QStringList findings = audit.run();
     INFO(findings.join(QStringLiteral("\n")).toStdString());
     CHECK(findings.isEmpty());
-    CHECK(audit.scannedFiles() == QStringList{});
+
+    // The audit is only as good as the files it found: the thirteen gui/qml
+    // ships, which is also the list gui/CMakeLists.txt hands qt_add_qml_module.
+    CHECK(audit.scannedFiles() ==
+          QStringList{QStringLiteral("AccountsPage.qml"), QStringLiteral("AppButton.qml"),
+                      QStringLiteral("AppShell.qml"), QStringLiteral("CardsPage.qml"), QStringLiteral("Field.qml"),
+                      QStringLiteral("LoansPage.qml"), QStringLiteral("Login.qml"), QStringLiteral("Main.qml"),
+                      QStringLiteral("MoveMoneyPage.qml"), QStringLiteral("Panel.qml"),
+                      QStringLiteral("PayeesPage.qml"), QStringLiteral("Picker.qml"), QStringLiteral("Pill.qml")});
 }