Repository navigation
PanelCatalog: extract widget-free catalog and load_panel_session() (PR 1) - #660
Conversation
dayfine
left a comment
There was a problem hiding this comment.
Reviewed SHA: d65712c
Review of PR 1 of docs/design/Headless-CC.md against lab/main cd86fe3, with three questions: is this the smallest change that does the job, is each test worth its lines, and does the GUI path behave the same. Read only; nothing was built locally (no build tree with Qt on this machine), apart from one clang++ -fsyntax-only check of the JSON call in finding B1.
Verdict
NEEDS_REWORK
The GUI behavior is unchanged as far as I can read it, and the three suggestions from the #657 review were mostly followed. But the test file does not compile, and the PR is about twice the size it needs to be: 306 of the 526 added lines are tests, and 5 of the 7 tests are low value or vacuous. Findings: 1 blocking, 3 major, 6 minor.
CI at this SHA: no C++ job has compiled it. Ubuntu Default failed at configure (Failed to download ONNX Runtime: "HTTP response code said error", not this PR; rerun it); the other five builds were still pending. code-health fails with 1 finding (M3). no-tabs passes. The description says it was not compiled locally either, so B1 is the first compile result this code has had.
Blocking
B1. PanelCatalog_Tests.cpp:210 does not compile. load_panel_session(holder, descriptor, obj) passes a JsonObject lvalue where const JsonValue& is expected. JsonValue converts only from JsonObject&& (JsonValue.h:88) and its copy constructor is private. Checked in isolation: no known conversion from 'JsonObject' to 'const JsonValue'. Use JsonValue(std::move(obj)), or drop the JSON fake altogether (see the test table).
Simplicity
What PR 2 needs from PR 1 is two things: identifier -> std::shared_ptr<const PanelDescriptor> without a widget, and the make/load sequence shared with the widget. Nothing else.
Forced by existing code (keep):
PanelEntryowns aunique_ptr,PanelHolder::load_panel()takes ashared_ptr<const>, andpanels()rebuilds the vector on every call. So a lookup must scan and convert; no cache, no raw pointer. This part offind_panel()is right.- The 13
*_Panels.hincludes and the 13 factory lines must move out ofPanelLists.cpp(it is aQWidgetfile). About 50 of the non-test lines are this move. - One
UnitTestsubclass per test kind (about 15 lines each) is the framework's cost.
Added by this PR (M1; can go):
| Item | Why it is not needed |
|---|---|
PanelCatalog(std::vector<...> lists) second constructor |
Only the tests call it. This is the "header symbol only for tests" the repo rule forbids. The #657 review suggested one constructor that takes the lists, with the caller adding the game factories; the PR kept the default constructor and added this one beside it. |
m_tab_map, find_category(), add() duplicate check in the catalog |
Category name to dropdown index is GUI state; only ProgramSelect::load_persistent_panel() reads it. Headless never asks for a category. Moving it buys std::optional<size_t>, std::less<> and three static_cast<int> in PanelLists.cpp, and is the only reason DuplicateCategoryTest exists. |
lists() accessor, const auto& lists = m_catalog.lists() in two functions |
Follows from the catalog owning the lists. |
PanelCatalogMatch (3 fields) |
display_name and descriptor are PanelEntry's two fields again. struct PanelMatch{ size_t category_index; PanelEntry entry; } is enough; unique_ptr converts to shared_ptr<const> at the load_panel_session() call. |
add() -> add_dropdown_entry(list, index) rename and split |
Follows from moving the lists; with them left in place ProgramSelect::add() is untouched. |
if (descriptor == nullptr) return false; in load_panel_session() |
No caller can reach it: the widget dereferences descriptor->identifier() to build the third argument first, and headless gets the pointer from a successful find_panel(). Document "non-null" and drop the branch and its test. |
class JsonValue; in PanelList.h |
PanelTools.h (already included) declares it. This line is also the code-health failure. |
} -> } // namespace PokemonAutomation in PanelList.h/.cpp |
Unrelated edit to existing lines. |
Simpler version (sketch):
Source/PanelCatalog.h(about 30 lines), no class:// Every program category, in dropdown order. std::vector<std::unique_ptr<PanelListDescriptor>> make_all_panel_lists(); struct PanelMatch{ size_t category_index; PanelEntry entry; }; // Scans each list's panels() for `identifier`. std::optional<PanelMatch> find_panel( const std::vector<std::unique_ptr<PanelListDescriptor>>& lists, std::string_view identifier );
Source/PanelCatalog.cpp(about 60 lines): the moved includes and factory list, plus the 12-line scan.PanelLists.cpp: the constructor doesfor (auto& list : make_all_panel_lists()){ add(std::move(list)); };select_program()callsfind_panel(m_lists, identifier).add(),m_lists,m_tab_map,load_persistent_panel(),change_list()andPanelLists.hstay as they are (keep the one good fix: copy the name beforepop_back(); the old code readback.name()after freeing it).load_panel_session()as it is, minus the null branch and the forward declaration.PanelListWidget.cppas it is.- Tests: the two HIGH rows below, about 110 lines.
Estimated size: about +240 / -60 (non-test about +125, of which about 50 are moved lines; tests about 110), against +526 / -82 now. If you prefer to keep a PanelCatalog class for HeadlessHost to hold, the same cuts apply: one constructor taking the lists, find_panel() only, no category map; that lands near +270.
Optional, for PR 2 to decide: PanelSession::load_json_from_global() already exists. If the helper called it, the panel_json parameter would go too, and headless would apply --options on the session afterwards. Not asked for here, because today's widget calls load_json(panels[id]), which also runs when the key is missing.
#657 suggestions:
| Suggestion | Followed? |
|---|---|
No persist_selection flag |
Yes. |
Widget keeps its own settings write and QMessageBox; helper has no Qt |
Yes. The helper returns bool and lets exceptions through to the widget's catch; that is fine. |
Catalog next to Source/PanelLists.{h,cpp}, in SourceFiles.cmake |
Yes. |
| Catalog takes its lists in the constructor, caller adds the factories | No: default constructor kept, a second one added for tests (M1). |
| Test: known identifier returns that descriptor, unknown returns null | Yes, and four more tests on top (M2). |
Tests (M2)
306 lines for 7 tests: 95 lines of fakes, 6 case structs, 2 runner classes. For each: what would it catch that a compile and the existing tests would not?
| # | Test | Catches | Rating |
|---|---|---|---|
| 1 | Lookup/first category after divider |
Dropping the descriptor == nullptr guard crashes on the divider; returning the entry index (1) for the category index (0). The scan had no test before. The display_name check adds nothing: the fake copies it from the descriptor. |
HIGH |
| 2 | Lookup/second category |
Only that the scan goes past the first list. Row 1 already tells category index from entry index. | LOW (two data lines; keep only if the fakes stay) |
| 3 | Lookup/missing identifier |
A lookup that returns something for an unknown id. The fall-through return std::nullopt is hard to get wrong. |
LOW (same) |
| 4 | LoadSession/loads panel and json |
Forgetting load_json() or passing other JSON. It replays the helper's four lines against mocks, and cannot see the one thing that matters, the order (load_json() before load_panel()), because it checks after both ran. Needs FakePanelSession and its JSON parsing only for this. |
LOW |
| 5 | LoadSession/declined intent skips load |
Ignoring report_new_panel_intent()'s result, which would replace the active panel when the holder said no. This is the contract both callers rely on. |
HIGH |
| 6 | LoadSession/null descriptor returns false |
Nothing a caller can hit; it covers a defensive branch that exists to be covered. | VACUOUS (delete with the branch) |
| 7 | DuplicateCategoryThrows |
A duplicate in a fake list. The real list is fixed at compile time and a real duplicate throws on the first GUI launch; this test cannot see it, and it is reachable only through the test-only constructor. | LOW (goes away when the check stays in ProgramSelect::add()) |
Result: 2 HIGH, 4 LOW, 1 VACUOUS. Keep 1 and 5 (2 and 3 may ride along as data rows). With 4 and 6 gone, FakePanelSession, the "key" JSON, LoadSessionInput::json_value (always "abc"), has_descriptor and loaded_value go; LoadSessionExpectation::result and ::loaded are equal in every row, so one field is left.
Correctness (GUI path)
No behavior change found.
- Load order. Before: intent,
make_panel(),load_json(panels[id]),load_panel(). NowPERSISTENT_SETTINGS().panels[id]is evaluated as an argument before the intent call, sooperator[]can insert a null entry earlier than before. Harmless withMainWindow: it declines only when the clicked panel is the active one, and thensave_settings()writes that same key.JsonObjectis astd::map, so the reference stays valid across that write. A holder that declines for other reasons would leave anullunder the id; worth one line in the helper's comment since PR 2 adds a second holder. - Selection persistence.
ProgramPanelis still written by the widget withiter->firstonly after a successful load, and""for an unknown name.ProgramCategoryis still written inchange_list(). Unchanged. - Error dialog. The
trynow also covers the intent call and thepanels[id]lookup; neither throws aPokemonAutomation::Exceptiontoday.QMessageBoxstays in the widget. Unchanged. select_program(). Same order of answers (unknown id, then locked, then switch).find_panel()moves out of a temporarypanels()vector, which is safe.- Construction. The lists are now built in
ProgramSelect's member initialization, before the dropdown exists; a duplicate category still throwsInternalProgramErrorfrom the constructor.
Major
- M1. Complexity added beyond PR 1's goal: see the table under Simplicity.
- M2. Test value: see the table under Tests.
- M3. Code health fails:
PanelList.h:19: header-commenton the newclass JsonValue;. Delete the line (also clears the forward-declaration advisory).
Minor
- m1. Test case shape:
namesits insideinputin both case structs. The rule is name / input / expectation, name not in the input. - m2.
FakePanelHolder::intent_calledis set and never read. - m3.
load_panel_session(PanelHolder& holder, ...): output parameter first (out_param_orderadvisory, twice). Putholderlast. - m4.
FakePanelDescriptorpasses"", "", PanelQualityStanding::DEVELOPER, falseto a 7-argument constructor with no parameter comments (/*doc_link=*/"",/*restore_defaults_button=*/false). - m5.
string_concatadvisories atPanelCatalog.cpp:62andPanelCatalog_Tests.cpp:230, 245: usestd::format. - m6. The description does not follow the fork format (one-sentence summary, short bullets, a Testing section) and should say plainly that nothing has compiled yet; update it once CI has built the head.
make_all_panel_lists() and find_panel(lists, id) replace PanelCatalog; ProgramSelect keeps its lists, category map and add(). Drop the unreachable null branch in load_panel_session() (holder now last) and the JsonValue forward declaration. Tests: lookup past a divider and declined intent skips load.
Base:
lab/main(cd86fe364); the diff shows only this change.PR 1 of
docs/design/Headless-CC.md: headless mode needs to find a panel by identifier and load it without the program-list widget. This moves the panel-list factories out of the Qt filePanelLists.cppinto two free functions inSource/PanelCatalog.{h,cpp},make_all_panel_lists()andfind_panel(lists, identifier), and shares the intent/make/load-JSON/install sequence betweenPanelListWidgetand the coming headless host asload_panel_session().ProgramSelectkeeps its lists, category map andadd(), so GUI behavior (selection persistence, the error dialog,select_program()) is unchanged; about 50 of the ~305 added lines are the moved factory list. Two newPanelCatalogunit tests cover a lookup past a divider and a declined intent that must not load anything; the touched files were syntax-checked locally with the app's compile flags, and CI builds and runs the tests.