diff --git a/SerialPrograms/Source/CommonFramework/Panels/ProgramDescriptor.h b/SerialPrograms/Source/CommonFramework/Panels/ProgramDescriptor.h index fc45d225b7..8bd01f8ffa 100644 --- a/SerialPrograms/Source/CommonFramework/Panels/ProgramDescriptor.h +++ b/SerialPrograms/Source/CommonFramework/Panels/ProgramDescriptor.h @@ -42,6 +42,21 @@ struct PrecheckSummary{ bool skippable = false; }; +// How one precheck ended in a checks-only run. +enum class PrecheckReportStatus{ + PASSED, + FAILED, + SKIPPED, +}; + +// What one precheck found in a checks-only run. On FAILED, the message +// tells the user what to fix. +struct PrecheckReport{ + std::string name = {}; + PrecheckReportStatus status = PrecheckReportStatus::PASSED; + std::string message = {}; +}; + class ProgramDescriptor : public PanelDescriptor{ diff --git a/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun.cpp b/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun.cpp new file mode 100644 index 0000000000..09f0644c4e --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun.cpp @@ -0,0 +1,117 @@ +/* Program Precheck Run + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#include +#include +#include "Common/Cpp/Json/JsonObject.h" +#include "ProgramPrecheckRun.h" + +namespace PokemonAutomation{ + +namespace{ + + +std::string key_path(std::string_view prefix, std::string_view key){ + return prefix.empty() ? std::string(key) : std::format("{}.{}", prefix, key); +} + +// Puts the values of `candidate` into `target`, an object, recursing into +// groups. `prefix` is the key path of `target`. +std::optional merge_into(const JsonObject& candidate, std::string_view prefix, JsonObject& target){ + for (const auto& item : candidate){ + const std::string path = key_path(prefix, item.first); + JsonValue* slot = target.get_value(item.first); + if (slot == nullptr){ + return RefusedOption{path, std::format("The program has no option {}.", path)}; + } + JsonObject* group = slot->to_object(); + const JsonObject* values = item.second.to_object(); + if (group != nullptr && values != nullptr){ + std::optional refused = merge_into(*values, path, *group); + if (refused){ + return refused; + } + continue; + } + if (group != nullptr || values != nullptr){ + return RefusedOption{path, std::format("Option {} is a group: its value is an object of its own options.", path)}; + } + *slot = item.second.clone(); + } + return std::nullopt; +} + +bool same_value(const JsonValue& x, const JsonValue& y){ + if (x.is_float() && y.is_float()){ + return x.to_double_default() == y.to_double_default(); + } + return x == y; +} + +std::optional find_refused_in(const JsonObject& candidate, const JsonObject& loaded, std::string_view prefix){ + for (const auto& item : candidate){ + const std::string path = key_path(prefix, item.first); + const JsonValue* now = loaded.get_value(item.first); + if (now == nullptr){ + return RefusedOption{path, std::format("The program has no option {}.", path)}; + } + const JsonObject* values = item.second.to_object(); + const JsonObject* group = now->to_object(); + if (values != nullptr && group != nullptr){ + std::optional refused = find_refused_in(*values, *group, path); + if (refused){ + return refused; + } + continue; + } + if (!same_value(item.second, *now)){ + return RefusedOption{ + path, + std::format("The program holds {} for {}, not {}.", now->dump(-1), path, item.second.dump(-1)) + }; + } + } + return std::nullopt; +} + + +} // namespace + + + +std::expected merge_candidate_options( + const JsonValue& current, const JsonValue& candidate +){ + const JsonObject* values = candidate.to_object(); + if (values == nullptr){ + return std::unexpected(RefusedOption{"", "The options to check must be a JSON object."}); + } + JsonValue merged = current.clone(); + JsonObject* target = merged.to_object(); + if (target == nullptr){ + return std::unexpected(RefusedOption{"", "The program's options are not a JSON object."}); + } + std::optional refused = merge_into(*values, "", *target); + if (refused){ + return std::unexpected(std::move(*refused)); + } + return merged; +} + +std::optional find_refused_option( + const JsonValue& candidate, const JsonValue& loaded +){ + const JsonObject* values = candidate.to_object(); + const JsonObject* now = loaded.to_object(); + if (values == nullptr || now == nullptr){ + return RefusedOption{"", "The options to check must be a JSON object."}; + } + return find_refused_in(*values, *now, ""); +} + + + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun.h b/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun.h new file mode 100644 index 0000000000..54ba2023bd --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun.h @@ -0,0 +1,65 @@ +/* Program Precheck Run + * + * From: https://github.com/PokemonAutomation/ + * + * A checks-only run of a program (ProgramSession::run_prechecks_only()): + * candidate options are loaded over the current ones, the program's + * prechecks run without starting it, and the prior options are loaded back. + * The lab's "preflight" command uses it to find a setup mistake before a run + * resets or saves anything. + * + */ + +#ifndef PokemonAutomation_CommonFramework_ProgramPrecheckRun_H +#define PokemonAutomation_CommonFramework_ProgramPrecheckRun_H + +#include +#include +#include +#include +#include "Common/Cpp/Json/JsonValue.h" +#include "CommonFramework/Panels/ProgramDescriptor.h" + +namespace PokemonAutomation{ + + +// A candidate option the program refused, and why. The key is a dotted key +// path ("NOTIFICATIONS.Enabled"); it is empty when the program refused the +// combination of options (check_validity()), which names no key. +struct RefusedOption{ + std::string key = {}; + std::string message = {}; +}; + +// What a checks-only run found. +struct PrecheckOnlyRun{ + // Set when the program refused the candidate options; no check ran. + std::optional refused = {}; + // The checks in the order they ran, up to the first FAILED one. Nothing + // when the program declares no precheck list, or refused the options. + std::optional> checks = {}; + // Whether the program holds the prior options again afterwards. + bool restored = false; +}; + + +// `current` (a program's option JSON) with the values of `candidate` put in. +// A candidate is an object of option keys; a group's value is an object of +// the group's own keys, of which only those given change. Refuses a key that +// `current` does not have, or a candidate that is not an object. +std::expected merge_candidate_options( + const JsonValue& current, const JsonValue& candidate +); + +// The first option of `candidate` whose value `loaded` (the options read +// back after loading the merged candidate) does not hold: a number clamped +// to its bounds, a disabled or unknown choice ignored. Numbers compare by +// value, so 2 and 2.0 are the same. +std::optional find_refused_option( + const JsonValue& candidate, const JsonValue& loaded +); + + + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun_Tests.cpp b/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun_Tests.cpp new file mode 100644 index 0000000000..33d15b3b9e --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun_Tests.cpp @@ -0,0 +1,194 @@ +/* Program Precheck Run - Tests + * + * From: https://github.com/PokemonAutomation/ + * + * How a checks-only run stages candidate options: the merge over the current + * options (groups keep the keys not given, unknown keys are refused), and + * the check that the program then holds every candidate value. + * + */ + +#include +#include +#include +#include +#include "Common/Cpp/Json/JsonValue.h" +#include "Common/Cpp/TestRunners/UnitTest.h" +#include "ProgramPrecheckRun.h" +#include "ProgramPrecheckRun_Tests.h" + +namespace PokemonAutomation{ + +namespace{ + + +constexpr std::string_view CURRENT = R"({"COUNT":5,"NOTIFICATIONS":{"Enabled":true,"Screenshot":false},"SPEED":0.5})"; + + +struct MergeInput{ + std::string candidate = {}; +}; +struct MergeExpectation{ + std::optional merged = {}; // Compact JSON with sorted keys, when merged. + std::optional refused_key = {}; // When refused. +}; +struct MergeCase{ + std::string name; + MergeInput input; + MergeExpectation expectation; +}; + +UnitTestResult check(const MergeCase& c){ + const std::expected merged = + merge_candidate_options(parse_json(std::string(CURRENT)), parse_json(c.input.candidate)); + if (!merged){ + if (c.expectation.refused_key == merged.error().key){ + return true; + } + return std::format("refused {} ({}), expected {}", merged.error().key, merged.error().message, + c.expectation.merged.value_or("a refusal of another key")); + } + const std::string text = merged->dump(-1); + if (c.expectation.merged == text){ + return true; + } + return std::format("merged to\n{}\nexpected {}", text, c.expectation.merged.value_or("a refusal")); +} + +class Test_MergeCandidateOptions : public UnitTest{ +public: + explicit Test_MergeCandidateOptions(MergeCase test_case) + : UnitTest(std::format("CommonFramework::ProgramPrecheckRun - merge - {}", test_case.name)) + , m_case(std::move(test_case)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return check(m_case); + } + +private: + MergeCase m_case; +}; + +const MergeCase MERGE_CASES[] = { + { + .name = "a value replaces the current one, the rest stay", + .input = {.candidate = R"({"COUNT":7})"}, + .expectation = {.merged = R"({"COUNT":7,"NOTIFICATIONS":{"Enabled":true,"Screenshot":false},"SPEED":0.5})"}, + }, + { + .name = "a group keeps the keys not given", + .input = {.candidate = R"({"NOTIFICATIONS":{"Screenshot":true}})"}, + .expectation = {.merged = R"({"COUNT":5,"NOTIFICATIONS":{"Enabled":true,"Screenshot":true},"SPEED":0.5})"}, + }, + { + .name = "an empty candidate changes nothing", + .input = {.candidate = R"({})"}, + .expectation = {.merged = std::string(CURRENT)}, + }, + { + .name = "an unknown key is refused", + .input = {.candidate = R"({"COUNT":7,"SPEEED":1.0})"}, + .expectation = {.refused_key = "SPEEED"}, + }, + { + .name = "an unknown key in a group is refused with its key path", + .input = {.candidate = R"({"NOTIFICATIONS":{"Sound":true}})"}, + .expectation = {.refused_key = "NOTIFICATIONS.Sound"}, + }, + { + .name = "a value for a group is refused", + .input = {.candidate = R"({"NOTIFICATIONS":false})"}, + .expectation = {.refused_key = "NOTIFICATIONS"}, + }, + { + .name = "a candidate that is not an object is refused", + .input = {.candidate = R"([1,2])"}, + .expectation = {.refused_key = ""}, + }, +}; + + +struct LoadedInput{ + std::string candidate = {}; + std::string loaded = {}; // The options read back after loading the merged candidate. +}; +struct LoadedExpectation{ + std::optional refused_key = {}; // None: the program holds every value. +}; +struct LoadedCase{ + std::string name; + LoadedInput input; + LoadedExpectation expectation; +}; + +UnitTestResult check(const LoadedCase& c){ + const std::optional refused = + find_refused_option(parse_json(c.input.candidate), parse_json(c.input.loaded)); + const std::optional key = refused ? std::optional(refused->key) : std::nullopt; + if (key == c.expectation.refused_key){ + return true; + } + const std::string got = refused ? std::format("{} ({})", refused->key, refused->message) : "nothing"; + return std::format("refused {}, expected {}", got, c.expectation.refused_key.value_or("nothing")); +} + +class Test_FindRefusedOption : public UnitTest{ +public: + explicit Test_FindRefusedOption(LoadedCase test_case) + : UnitTest(std::format("CommonFramework::ProgramPrecheckRun - loaded - {}", test_case.name)) + , m_case(std::move(test_case)) + {} + virtual UnitTestResult run(Logger&, CancellableScope&) const override{ + return check(m_case); + } + +private: + LoadedCase m_case; +}; + +const LoadedCase LOADED_CASES[] = { + { + .name = "every value held", + .input = { + .candidate = R"({"COUNT":7,"NOTIFICATIONS":{"Screenshot":true}})", + .loaded = R"({"COUNT":7,"NOTIFICATIONS":{"Enabled":true,"Screenshot":true},"SPEED":0.5})", + }, + .expectation = {}, + }, + { + .name = "an integer for a number option is the same value", + .input = {.candidate = R"({"SPEED":2})", .loaded = R"({"COUNT":5,"SPEED":2.0})"}, + .expectation = {}, + }, + { + .name = "a number clamped to its bounds", + .input = {.candidate = R"({"COUNT":70})", .loaded = R"({"COUNT":10,"SPEED":0.5})"}, + .expectation = {.refused_key = "COUNT"}, + }, + { + .name = "a disabled choice in a group, ignored", + .input = { + .candidate = R"({"NOTIFICATIONS":{"Screenshot":true}})", + .loaded = R"({"NOTIFICATIONS":{"Enabled":true,"Screenshot":false}})", + }, + .expectation = {.refused_key = "NOTIFICATIONS.Screenshot"}, + }, +}; + + +} // namespace + + + +void add_tests_ProgramPrecheckRun(UnitTestDatabase& database){ + for (const MergeCase& c : MERGE_CASES){ + database.add(c); + } + for (const LoadedCase& c : LOADED_CASES){ + database.add(c); + } +} + + + +} // namespace PokemonAutomation diff --git a/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun_Tests.h b/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun_Tests.h new file mode 100644 index 0000000000..401f3461f0 --- /dev/null +++ b/SerialPrograms/Source/CommonFramework/ProgramPrecheckRun_Tests.h @@ -0,0 +1,21 @@ +/* Program Precheck Run - Tests + * + * From: https://github.com/PokemonAutomation/ + * + */ + +#ifndef PokemonAutomation_CommonFramework_ProgramPrecheckRun_Tests_H +#define PokemonAutomation_CommonFramework_ProgramPrecheckRun_Tests_H + +#include "Common/Cpp/TestRunners/UnitTestDatabase.h" + +namespace PokemonAutomation{ + + +// Adds the tests of the checks-only run's option staging. +void add_tests_ProgramPrecheckRun(UnitTestDatabase& database); + + + +} // namespace PokemonAutomation +#endif diff --git a/SerialPrograms/Source/CommonFramework/ProgramSession.cpp b/SerialPrograms/Source/CommonFramework/ProgramSession.cpp index 04565b8007..344ffd5a17 100644 --- a/SerialPrograms/Source/CommonFramework/ProgramSession.cpp +++ b/SerialPrograms/Source/CommonFramework/ProgramSession.cpp @@ -4,9 +4,11 @@ * */ +#include #include #include "Common/Cpp/Exceptions.h" #include "Common/Cpp/PanicDump.h" +#include "Common/Cpp/ScopeExit.h" #include "Common/Cpp/Logging/GlobalLogger.h" #include "CommonFramework/GlobalSettingsPanel.h" #include "CommonFramework/Logging/Logger.h" @@ -43,6 +45,20 @@ ProgramSession::RunningProgramScope::RunningProgramScope(ProgramSession& session } session.m_scope = &m_scope; } +ProgramSession::RunningProgramScope::RunningProgramScope(ProgramSession& session, CancellableScope& parent) + : m_session(session) + , m_scope(parent) +{ + std::lock_guard lg(session.m_lock); + const ProgramState state = session.current_state(); + if (state != ProgramState::STOPPED){ + throw UserSetupError(session.m_logger, "Stop the program before checking it."); + } + if (session.m_scope != nullptr){ + throw UserSetupError(session.m_logger, "The program is already running its start checks."); + } + session.m_scope = &m_scope; +} ProgramSession::RunningProgramScope::~RunningProgramScope(){ { std::lock_guard lg(m_session.m_lock); @@ -101,6 +117,48 @@ std::optional> ProgramSession::precheck_summaries() } return m_instance->precheck_summaries(); } +PrecheckOnlyRun ProgramSession::run_prechecks_only(const JsonValue& candidate, CancellableScope& parent){ + RunningProgramScope running_scope(*this, parent); + const JsonValue prior = m_instance->to_json(); + std::expected merged = merge_candidate_options(prior, candidate); + if (!merged){ + return PrecheckOnlyRun{.refused = std::move(merged.error()), .checks = std::nullopt, .restored = true}; + } + + m_logger.log(std::format("Start checks only, with options: {}", candidate.dump(-1))); + PrecheckOnlyRun run; + { + ScopeExit restore([&]{ + m_instance->load_json(prior); + }); + m_instance->load_json(*merged); + run.refused = find_refused_option(candidate, m_instance->to_json()); + if (!run.refused){ + std::string error = m_instance->check_validity(); + if (!error.empty()){ + run.refused = RefusedOption{"", std::move(error)}; + } + } + if (!run.refused && m_instance->precheck_summaries()){ + const ProgramInfo program_info( + identifier(), + m_descriptor.category(), + m_descriptor.display_name(), + current_time() + ); + std::unique_ptr env = make_env(program_info); + run.checks = internal_run_prechecks(*env); + } + } + run.restored = m_instance->to_json() == prior; + if (!run.restored){ + m_logger.log("Start checks only: the prior options did not load back.", COLOR_RED); + } + return run; +} +std::optional> ProgramSession::internal_run_prechecks(ProgramEnvironment&){ + return std::nullopt; +} std::string ProgramSession::current_stats() const{ std::lock_guard lg(m_lock); if (m_current_stats){ @@ -254,7 +312,7 @@ std::string ProgramSession::start_program(ActionSource source, std::optional> precheck_summaries() const; + // A checks-only run on the calling thread, under `parent`: loads + // `candidate` (option keys to change, merge_candidate_options()) over + // the current options, runs the program's prechecks without starting it + // (internal_run_prechecks()), and loads the prior options back, + // also when a check throws. Start refuses while it runs, and nothing is + // saved to the settings file. Throws if the program is not STOPPED. + PrecheckOnlyRun run_prechecks_only(const JsonValue& candidate, CancellableScope& parent); + // - return struct that contains the list of missing resources and boolean upgrade_warning. // - upgrade_warning: is true if we need to warn the user to upgrade CC. @@ -134,6 +143,9 @@ class ProgramSession : public TrackableProgram{ protected: virtual std::unique_ptr make_env(const ProgramInfo& program_info) = 0; virtual void internal_run_program(ProgramEnvironment& env) = 0; + // The program's prechecks for run_prechecks_only(), under m_scope, up to + // and including the first FAILED one; nothing when it declares none. + virtual std::optional> internal_run_prechecks(ProgramEnvironment& env); virtual void internal_stop_program(); // virtual void restore_defaults(){ return; } @@ -204,6 +216,9 @@ class ProgramSession : public TrackableProgram{ class RunningProgramScope{ public: RunningProgramScope(ProgramSession& session); + // For a checks-only run: attached to `parent`, and only while the + // program is STOPPED. + RunningProgramScope(ProgramSession& session, CancellableScope& parent); ~RunningProgramScope(); private: diff --git a/SerialPrograms/Source/CommonFramework/Windows/Lab.md b/SerialPrograms/Source/CommonFramework/Windows/Lab.md index b62ee7b7ef..b6da3d3d73 100644 --- a/SerialPrograms/Source/CommonFramework/Windows/Lab.md +++ b/SerialPrograms/Source/CommonFramework/Windows/Lab.md @@ -103,6 +103,11 @@ holds the state file's fields (as `program.state` in lower case, `panel`, (`ProgramSession`, `ProgramTransition.h`), and a stop keeps its asker through `stopping` to `stopped`: an error or the run's end after a Stop does not change who stopped it. +- `program.options_hash`: the hash of the selected program's options (the + JSON the settings file saves for it, without `ConsoleSetup`): SHA-256 in + hex of its compact text with sorted keys, so any option change, from the + UI or from `set`, changes it. Absent without a program. A logical change: + written at once. - `video.frame_seq` and `captured_at`: the newest frame from the console's video, counted since the app started. `state` is `live` while that frame is at most 2 s old, `stale` when older, `missing` without video. @@ -124,6 +129,7 @@ program. | `stop` | What clicking Stop Program does. Refused unless the program is `RUNNING`. The request goes on; the program stops in the background. | | `state` | Prints the state file's lines into the journal. (In the Command File Runner program, `state [image]` prints the detectors that fire instead; from the channel use `detect` per detector.) | | `describe_program` | Prints the selected program's id and the static contract of its options as one line, `describe_program `; see [Describe program](#describe-program). Reads only: needs no owner token and no console. Refused when the selected panel is not a program. | +| `preflight JSON` | Runs the selected program's start checks with these options, without starting it, and puts the prior options back; prints one line, `preflight `; see [Preflight](#preflight). Needs the owner token, like a press. Refused unless the program is `STOPPED`. | | `snapshot LABEL [TIMEOUT_MS]` | Saves the first video frame newer than this line as `_