Improve error diagnostics and add sanitizer run support

Author: GaspardKirira

include/vix/cli/commands/check/CheckDetail.hpp

@@ -87,6 +87,9 @@ namespace vix::commands::CheckCommand::detail
     /// Enable UBSan only.
     bool enableUbsanOnly = false;
 
+    /// Enable ThreadSanitizer only.
+    bool enableThreadSanitizer = false;
+
     /// Enable SQLite backend.
     bool withSqlite = false;
 

include/vix/cli/commands/run/RunDetail.hpp

@@ -130,8 +130,9 @@ namespace vix::commands::RunCommand::detail
     bool forceServerLike = false;
     bool forceScriptLike = false;
 
-    bool enableSanitizers = false; // ASan + UBSan
-    bool enableUbsanOnly = false;  // UBSan only
+    bool enableSanitizers = false;      // ASan + UBSan
+    bool enableUbsanOnly = false;       // UBSan only
+    bool enableThreadSanitizer = false; // TSan only
 
     bool withSqlite = false;
     bool withMySql = false;
@@ -451,6 +452,27 @@ namespace vix::commands::RunCommand::detail
     return opt.timeoutSec;
   }
 
+  /**
+   * @brief Checks whether any sanitizer mode is enabled.
+   *
+   * This includes:
+   * - ASan+UBSan
+   * - UBSan-only
+   * - ThreadSanitizer
+   *
+   * @param enableSanitizers True when ASan+UBSan mode is enabled.
+   * @param enableUbsanOnly True when UBSan-only mode is enabled.
+   * @param enableThreadSanitizer True when ThreadSanitizer mode is enabled.
+   * @return True if any sanitizer mode is active.
+   */
+  inline bool want_any_sanitizer(
+      bool enableSanitizers,
+      bool enableUbsanOnly,
+      bool enableThreadSanitizer) noexcept
+  {
+    return enableSanitizers || enableUbsanOnly || enableThreadSanitizer;
+  }
+
   /**
    * @brief Normalize a cwd string to an absolute path when possible.
    */

include/vix/cli/commands/run/RunScriptHelpers.hpp

@@ -12,35 +12,147 @@
  */
 #ifndef VIX_RUN_SCRIPT_HELPERS_HPP
 #define VIX_RUN_SCRIPT_HELPERS_HPP
+
 #include <filesystem>
 #include <optional>
 #include <string>
 #include <string_view>
 #include <vector>
+
 namespace vix::commands::RunCommand::detail
 {
   namespace fs = std::filesystem;
+
+  /**
+   * @brief Prints the watch-mode restart banner.
+   *
+   * @param path Path of the file that triggered the restart.
+   * @param label Message displayed while rebuilding or restarting.
+   */
   void print_watch_restart_banner(const fs::path &path, std::string_view label);
-  std::string sanitizer_mode_string(bool enableSanitizers, bool enableUbsanOnly);
-  bool want_sanitizers(bool enableSanitizers, bool enableUbsanOnly);
+
+  /**
+   * @brief Checks whether ASan+UBSan or UBSan-only mode is enabled.
+   *
+   * This helper intentionally does not include ThreadSanitizer.
+   * For ASan, UBSan, and TSan together, use want_any_sanitizer()
+   * from RunDetail.hpp.
+   *
+   * @param enableSanitizers True when ASan+UBSan mode is enabled.
+   * @param enableUbsanOnly True when UBSan-only mode is enabled.
+   * @return True if ASan+UBSan or UBSan-only mode is active.
+   */
+  bool want_sanitizers(
+      bool enableSanitizers,
+      bool enableUbsanOnly);
+
+  /**
+   * @brief Returns the sanitizer mode string used by generated CMake projects.
+   *
+   * Possible return values:
+   * - "asan_ubsan"
+   * - "ubsan"
+   * - "tsan"
+   * - "none"
+   *
+   * @param enableSanitizers True when ASan+UBSan mode is enabled.
+   * @param enableUbsanOnly True when UBSan-only mode is enabled.
+   * @param enableThreadSanitizer True when ThreadSanitizer mode is enabled.
+   * @return Sanitizer mode string.
+   */
+  std::string sanitizer_mode_string(
+      bool enableSanitizers,
+      bool enableUbsanOnly,
+      bool enableThreadSanitizer);
+
+  /**
+   * @brief Builds the configuration signature for generated script CMake projects.
+   *
+   * The signature is used to decide whether a cached generated CMake project
+   * must be reconfigured. It includes every option that can affect the produced
+   * binary, including sanitizer mode, script flags, and optional database support.
+   *
+   * @param useVixRuntime True if the script links against the Vix runtime.
+   * @param enableSanitizers True when ASan+UBSan mode is enabled.
+   * @param enableUbsanOnly True when UBSan-only mode is enabled.
+   * @param enableThreadSanitizer True when ThreadSanitizer mode is enabled.
+   * @param scriptFlags Compiler/linker flags forwarded to script mode.
+   * @param withSqlite True if SQLite support is enabled.
+   * @param withMySql True if MySQL support is enabled.
+   * @return Stable configuration signature string.
+   */
   std::string make_script_config_signature(
       bool useVixRuntime,
       bool enableSanitizers,
       bool enableUbsanOnly,
+      bool enableThreadSanitizer,
       const std::vector<std::string> &scriptFlags,
       bool withSqlite,
       bool withMySql);
+
+  /**
+   * @brief Starts the watch-mode spinner.
+   *
+   * @param label Text displayed next to the spinner.
+   */
   void watch_spinner_start(std::string label);
+
+  /**
+   * @brief Stops the watch-mode spinner.
+   */
   void watch_spinner_stop();
+
+  /**
+   * @brief Temporarily stops the watch spinner before printing output.
+   */
   void watch_spinner_pause_for_output();
+
 #ifndef _WIN32
-  void apply_sanitizer_env_if_needed(bool enableSanitizers, bool enableUbsanOnly);
+  /**
+   * @brief Applies sanitizer-related runtime environment variables.
+   *
+   * On POSIX systems, this configures ASan, UBSan, or TSan environment
+   * variables so sanitizer reports are deterministic and easier for Vix
+   * to capture and convert into friendly diagnostics.
+   *
+   * @param enableSanitizers True when ASan+UBSan mode is enabled.
+   * @param enableUbsanOnly True when UBSan-only mode is enabled.
+   * @param enableThreadSanitizer True when ThreadSanitizer mode is enabled.
+   */
+  void apply_sanitizer_env_if_needed(
+      bool enableSanitizers,
+      bool enableUbsanOnly,
+      bool enableThreadSanitizer);
 #endif
 
+  /**
+   * @brief Finds a precompiled Vix header if available.
+   *
+   * @return Path to the PCH file, or std::nullopt if not found.
+   */
   std::optional<fs::path> find_vix_pch();
+
+  /**
+   * @brief Finds the installed Vix include directory.
+   *
+   * @return Path to the include directory, or std::nullopt if not found.
+   */
   std::optional<fs::path> find_vix_include_dir();
+
+  /**
+   * @brief Finds the installed Vix library.
+   *
+   * @return Path to the Vix library, or std::nullopt if not found.
+   */
   std::optional<fs::path> find_vix_lib();
+
+  /**
+   * @brief Finds all installed Vix module libraries.
+   *
+   * @return List of discovered Vix module library paths.
+   */
   std::vector<fs::path> find_vix_all_module_libs();
 
 } // namespace vix::commands::RunCommand::detail
+
 #endif

include/vix/cli/errors/build/BuildErrorDetectors.hpp

@@ -19,6 +19,6 @@
 namespace vix::cli::errors::build
 {
   bool handleBuildErrors(std::string_view log);
-}
+} // namespace vix::cli::errors::build
 
 #endif

include/vix/cli/errors/build/CMakeBuildErrors.hpp

@@ -19,6 +19,6 @@
 namespace vix::cli::errors::build
 {
   bool handleCMakeBuildError(std::string_view log);
-}
+} // namespace vix::cli::errors::build
 
 #endif

include/vix/cli/errors/rules/UncaughtExceptionRule.hpp

@@ -1,3 +1,15 @@
+/**
+ *
+ *  @file UncaughtExceptionRule.hpp
+ *  @author Gaspard Kirira
+ *
+ *  Copyright 2025, Gaspard Kirira.  All rights reserved.
+ *  https://github.com/vixcpp/vix
+ *  Use of this source code is governed by a MIT license
+ *  that can be found in the License file.
+ *
+ *  Vix.cpp
+ */
 #pragma once
 
 #include <filesystem>

include/vix/cli/errors/runtime/RuntimeRuleUtils.hpp

@@ -22,13 +22,38 @@
 
 namespace vix::cli::errors::runtime
 {
+  struct RuntimeLocation
+  {
+    std::filesystem::path file{};
+    int line = 0;
+    int column = 1;
+
+    [[nodiscard]] bool valid() const noexcept
+    {
+      return !file.empty() && line > 0;
+    }
+  };
+
   bool icontains(const std::string &text, const std::string &needle);
 
   std::string strip_line_comment(const std::string &line);
 
   std::optional<std::vector<std::string>> read_file_lines(
       const std::filesystem::path &path);
 
+  RuntimeLocation find_best_runtime_location(
+      const std::string &log,
+      const std::filesystem::path &sourceFile);
+
+  RuntimeLocation find_best_runtime_location_or_source_hint(
+      const std::string &log,
+      const std::filesystem::path &sourceFile,
+      const std::vector<std::string> &sourcePatterns);
+
+  std::string make_at_text(
+      const RuntimeLocation &location,
+      const std::filesystem::path &sourceFile);
+
   vix::cli::errors::CompilerError make_runtime_location(
       const std::filesystem::path &sourceFile,
       int line,