BUG: Treat a missing preferences file as a normal first run (#1827)

* Application::loadPreferences() returned an error Result when the
  preferences file did not exist. The Application constructor then
  printed "Error initializing application: ..." to stderr on the first
  run of every executable on a fresh account. The CTest build log parser
  matches that line and reports the build as a failure.
* The missing-file case is expected. Default preferences are used and
  the file is written on shutdown. loadPreferences() now returns a valid
  Result for that case and keeps the error for unreadable or malformed
  files.
* Add a loadPreferences(const std::filesystem::path&) overload so the
  behavior can be tested without the user's real preferences file.
* Move the Preferences file error codes into the Preferences class as
  public constants so callers can identify the missing-file case.
* Add tests for the missing-file, malformed-JSON, and direct
  Preferences::loadFromFile cases.

Signed-off-by: Michael Jackson <mike.jackson@bluequartz.net>

Author: imikejackson

src/simplnx/Core/Application.cpp

@@ -195,17 +195,24 @@ std::filesystem::path Application::getCurrentDir() const
 }
 
 Result<> Application::loadPreferences()
+{
+  return loadPreferences(Preferences::DefaultFilePath(getApplicationName(this)));
+}
+
+Result<> Application::loadPreferences(const std::filesystem::path& filepath)
 {
   if(m_Preferences == nullptr)
   {
     m_Preferences = std::make_unique<Preferences>();
   }
-  std::string applicationName = getApplicationName(this);
-  const auto filepath = Preferences::DefaultFilePath(applicationName);
-
   auto result = m_Preferences->loadFromFile(filepath);
   if(result.invalid())
   {
+    if(!result.errors().empty() && result.errors()[0].code == Preferences::k_FileDoesNotExist_Code)
+    {
+      // On the first run, defaults are used and the preferences file is written on shutdown.
+      return {};
+    }
     return MakeErrorResult(-1, fmt::format("Could not load preferences from '{}': {}", filepath.string(), result.errors().empty() ? "unknown error" : result.errors()[0].message));
   }
   return result;

src/simplnx/Core/Application.hpp

@@ -114,10 +114,21 @@ class SIMPLNX_EXPORT Application
 
   /**
    * @brief Loads preferences from the default file path.
-   * @return Error when the file cannot load or parse.
+   * @return Success if the file loads or does not exist; error for other load or parse failures.
+   *
+   * On the first run, defaults are used and the preferences file is written on shutdown.
    */
   Result<> loadPreferences();
 
+  /**
+   * @brief Loads preferences from the specified file path.
+   * @param filepath Preferences JSON file to load.
+   * @return Success if the file loads or does not exist; error for other load or parse failures.
+   *
+   * A missing file leaves the current preferences and defaults unchanged.
+   */
+  Result<> loadPreferences(const std::filesystem::path& filepath);
+
   /**
    * @brief Returns no JSON pipeline builder.
    * @return nullptr.

src/simplnx/Core/Preferences.cpp

@@ -29,11 +29,6 @@ constexpr StringLiteral k_DefaultFileName = "preferences.json";
 constexpr int64 k_ReducedDataStructureSize = 3221225472; // 3 GB
 constexpr bool k_AutoRangeComputationDefault = false;
 
-constexpr int32 k_FailedToCreateDirectory_Code = -585;
-constexpr int32 k_FileDoesNotExist_Code = -586;
-constexpr int32 k_FileCouldNotOpen_Code = -587;
-constexpr int32 k_JsonParseError_Code = -588;
-
 constexpr StringLiteral k_FailedToCreateDirectory_Message = "Failed to create the parent directory when saving Preferences. Check that the path is valid and writable.";
 constexpr StringLiteral k_FileDoesNotExist_Message = "Preferences file does not exist";
 constexpr StringLiteral k_FileCouldNotOpen_Message = "Could not open Preferences file";
@@ -208,13 +203,13 @@ Result<> Preferences::saveToFile(const std::filesystem::path& filepath) const
 {
   if(!std::filesystem::exists(filepath.parent_path()) && !std::filesystem::create_directories(filepath.parent_path()))
   {
-    return MakeErrorResult(k_FailedToCreateDirectory_Code, k_FailedToCreateDirectory_Message);
+    return MakeErrorResult(Preferences::k_FailedToCreateDirectory_Code, k_FailedToCreateDirectory_Message);
   }
 
   std::ofstream fileStream(filepath);
   if(!fileStream.is_open())
   {
-    return MakeErrorResult(k_FileCouldNotOpen_Code, k_FileCouldNotOpen_Message);
+    return MakeErrorResult(Preferences::k_FileCouldNotOpen_Code, k_FileCouldNotOpen_Message);
   }
 
   fileStream << m_Values;
@@ -225,19 +220,19 @@ Result<> Preferences::loadFromFile(const std::filesystem::path& filepath)
 {
   if(!std::filesystem::exists(filepath))
   {
-    return MakeErrorResult(k_FileDoesNotExist_Code, k_FileDoesNotExist_Message);
+    return MakeErrorResult(Preferences::k_FileDoesNotExist_Code, k_FileDoesNotExist_Message);
   }
 
   std::ifstream fileStream(filepath);
   if(!fileStream.is_open())
   {
-    return MakeErrorResult(k_FileCouldNotOpen_Code, k_FileCouldNotOpen_Message);
+    return MakeErrorResult(Preferences::k_FileCouldNotOpen_Code, k_FileCouldNotOpen_Message);
   }
 
   nlohmann::json parsedResult = nlohmann::json::parse(fileStream, nullptr, false);
   if(parsedResult.is_discarded())
   {
-    return MakeErrorResult(k_JsonParseError_Code, k_JsonParseError_Message);
+    return MakeErrorResult(Preferences::k_JsonParseError_Code, k_JsonParseError_Message);
   }
 
   m_Values = parsedResult;

src/simplnx/Core/Preferences.hpp

@@ -41,6 +41,11 @@ class SIMPLNX_EXPORT Preferences
   friend class AbstractPlugin;
 
 public:
+  static inline constexpr int32 k_FailedToCreateDirectory_Code = -585;
+  static inline constexpr int32 k_FileDoesNotExist_Code = -586;
+  static inline constexpr int32 k_FileCouldNotOpen_Code = -587;
+  static inline constexpr int32 k_JsonParseError_Code = -588;
+
   static inline constexpr StringLiteral k_LargeDataSize_Key = "large_data_size";
 
   // Migration reads this legacy key. The core does not write it.

test/AppTest.cpp

@@ -1,11 +1,15 @@
 
+#include "simplnx/Common/ScopeGuard.hpp"
 #include "simplnx/Core/Application.hpp"
 #include "simplnx/Core/Preferences.hpp"
 
+#include "simplnx/unit_test/simplnx_test_dirs.hpp"
+
 #include <catch2/catch.hpp>
 
 #include <filesystem>
 #include <fstream>
+#include <system_error>
 
 using namespace nx::core;
 namespace fs = std::filesystem;
@@ -96,6 +100,61 @@ TEST_CASE("Application::loadPreferences", "[Application]")
   }
 }
 
+TEST_CASE("Application::loadPreferences from a specified path", "[Application]")
+{
+  const fs::path tempDir = fs::path(unit_test::k_BinaryTestOutputDir.view()) / ("ApplicationPreferences_" + Uuid::GenerateV4().str());
+  REQUIRE(fs::create_directories(tempDir));
+  auto cleanup = MakeScopeGuard([&tempDir]() noexcept {
+    std::error_code error;
+    fs::remove_all(tempDir, error);
+  });
+  const fs::path filepath = tempDir / "preferences.json";
+
+  SECTION("A missing preferences file is a normal first run")
+  {
+    auto app = Application::GetOrCreateInstance();
+    REQUIRE_FALSE(fs::exists(filepath));
+
+    const auto result = app->loadPreferences(filepath);
+
+    REQUIRE(result.valid());
+    REQUIRE(result.warnings().empty());
+    REQUIRE(app->getPreferences() != nullptr);
+    REQUIRE_FALSE(fs::exists(filepath));
+  }
+
+  SECTION("Malformed JSON remains an application error")
+  {
+    {
+      std::ofstream file(filepath);
+      REQUIRE(file.is_open());
+      file << "{ not json";
+      file.close();
+      REQUIRE(file.good());
+    }
+    auto app = Application::GetOrCreateInstance();
+
+    const auto result = app->loadPreferences(filepath);
+
+    REQUIRE(result.invalid());
+    REQUIRE_FALSE(result.errors().empty());
+    REQUIRE(result.errors()[0].code == -1);
+    REQUIRE(result.errors()[0].message.find("Could not load preferences") != std::string::npos);
+  }
+
+  SECTION("Preferences reports the missing-file error code directly")
+  {
+    Preferences preferences;
+    REQUIRE_FALSE(fs::exists(filepath));
+
+    const auto result = preferences.loadFromFile(filepath);
+
+    REQUIRE(result.invalid());
+    REQUIRE_FALSE(result.errors().empty());
+    REQUIRE(result.errors()[0].code == Preferences::k_FileDoesNotExist_Code);
+  }
+}
+
 TEST_CASE("Application::savePreferences", "[Application]")
 {
   auto app = Application::GetOrCreateInstance();