Skip to content

PanelCatalog: extract widget-free catalog and load_panel_session() (PR 1) - #660

Merged
dayfine merged 3 commits into
lab/mainfrom
lab/panel-catalog
Nov 19, 2026
Merged

dayfine merged 3 commits into
lab/mainfrom
lab/panel-catalog

Conversation

@dayfine

@dayfine dayfine commented Nov 19, 2026 •

Copy link
Copy Markdown
Owner

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 file PanelLists.cpp into two free functions in Source/PanelCatalog.{h,cpp}, make_all_panel_lists() and find_panel(lists, identifier), and shares the intent/make/load-JSON/install sequence between PanelListWidget and the coming headless host as load_panel_session(). ProgramSelect keeps its lists, category map and add(), 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 new PanelCatalog unit 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.

@dayfine dayfine left a comment

Copy link
Copy Markdown
Owner Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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):

  • PanelEntry owns a unique_ptr, PanelHolder::load_panel() takes a shared_ptr<const>, and panels() rebuilds the vector on every call. So a lookup must scan and convert; no cache, no raw pointer. This part of find_panel() is right.
  • The 13 *_Panels.h includes and the 13 factory lines must move out of PanelLists.cpp (it is a QWidget file). About 50 of the non-test lines are this move.
  • One UnitTest subclass 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 does for (auto& list : make_all_panel_lists()){ add(std::move(list)); }; select_program() calls find_panel(m_lists, identifier). add(), m_lists, m_tab_map, load_persistent_panel(), change_list() and PanelLists.h stay as they are (keep the one good fix: copy the name before pop_back(); the old code read back.name() after freeing it).
  • load_panel_session() as it is, minus the null branch and the forward declaration. PanelListWidget.cpp as 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(). Now PERSISTENT_SETTINGS().panels[id] is evaluated as an argument before the intent call, so operator[] can insert a null entry earlier than before. Harmless with MainWindow: it declines only when the clicked panel is the active one, and then save_settings() writes that same key. JsonObject is a std::map, so the reference stays valid across that write. A holder that declines for other reasons would leave a null under the id; worth one line in the helper's comment since PR 2 adds a second holder.
  • Selection persistence. ProgramPanel is still written by the widget with iter->first only after a successful load, and "" for an unknown name. ProgramCategory is still written in change_list(). Unchanged.
  • Error dialog. The try now also covers the intent call and the panels[id] lookup; neither throws a PokemonAutomation::Exception today. QMessageBox stays in the widget. Unchanged.
  • select_program(). Same order of answers (unknown id, then locked, then switch). find_panel() moves out of a temporary panels() vector, which is safe.
  • Construction. The lists are now built in ProgramSelect's member initialization, before the dropdown exists; a duplicate category still throws InternalProgramError from 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-comment on the new class JsonValue;. Delete the line (also clears the forward-declaration advisory).

Minor

  • m1. Test case shape: name sits inside input in both case structs. The rule is name / input / expectation, name not in the input.
  • m2. FakePanelHolder::intent_called is set and never read.
  • m3. load_panel_session(PanelHolder& holder, ...): output parameter first (out_param_order advisory, twice). Put holder last.
  • m4. FakePanelDescriptor passes "", "", PanelQualityStanding::DEVELOPER, false to a 7-argument constructor with no parameter comments (/*doc_link=*/"", /*restore_defaults_button=*/false).
  • m5. string_concat advisories at PanelCatalog.cpp:62 and PanelCatalog_Tests.cpp:230, 245: use std::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.
@dayfine
dayfine merged commit 87d8957 into lab/main Nov 19, 2026
6 of 12 checks passed
@dayfine
dayfine deleted the lab/panel-catalog branch November 19, 2026 04:21
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant