🚀 Clear assertion greyed-out lines on restart and highlight issue locations

bindings/InterfaceBindings.cpp

@@ -74,6 +74,14 @@ void bindFramework(py::module& m) {
       .export_values()
       .finalize();
 
+  // Bind the Result enum
+  py::native_enum<Result>(m, "Result", "enum.Enum",
+                          "The result of an operation.")
+      .value("OK", OK, "Indicates that the operation was successful.")
+      .value("ERROR", ERROR, "Indicates that an error occurred.")
+      .export_values()
+      .finalize();
+
   // Bind the VariableValue union
   py::class_<VariableValue>(m, "VariableValue")
       .def(py::init<>())
@@ -166,6 +174,35 @@ Contains one element for each of the `num_states` states in the state vector.)")
       .doc() =
       "The settings that should be used to compile an assertion program.";
 
+  py::class_<LoadResult>(m, "LoadResult")
+      .def_readonly("result", &LoadResult::result,
+                    "The result of the load operation.")
+      .def_readonly(
+          "line", &LoadResult::line,
+          "The 1-based line of the error location, or 0 if unavailable.")
+      .def_readonly(
+          "column", &LoadResult::column,
+          "The 1-based column of the error location, or 0 if unavailable.")
+      .def_property_readonly(
+          "detail",
+          [](const LoadResult& result) -> py::object {
+            if (result.detail == nullptr) {
+              return py::none();
+            }
+            return py::str(result.detail);
+          },
+          "The error detail text, or None if unavailable.")
+      .def_property_readonly(
+          "message",
+          [](const LoadResult& result) -> py::object {
+            if (result.message == nullptr) {
+              return py::none();
+            }
+            return py::str(result.message);
+          },
+          "The full error message, or None if unavailable.")
+      .doc() = "Represents the structured result of a load operation.";
+
   py::class_<SimulationState>(m, "SimulationState")
       .def(py::init<>(), "Creates a new `SimulationState` instance.")
       .def(
@@ -174,12 +211,34 @@ Contains one element for each of the `num_states` states in the state vector.)")
       .def(
           "load_code",
           [](SimulationState* self, const char* code) {
-            checkOrThrow(self->loadCode(self, code));
+            const Result result = self->loadCode(self, code);
+            if (result != OK) {
+              const char* messagePtr = self->getLastErrorMessage
+                                           ? self->getLastErrorMessage(self)
+                                           : nullptr;
+              std::string message = messagePtr ? messagePtr : "";
+              if (message.empty()) {
+                message = "An error occurred while executing the operation";
+              }
+              throw std::runtime_error(message);
+            }
           },
           R"(Loads the given code into the simulation state.
 
 Args:
     code (str): The code to load.)")
+      .def(
+          "load_code_with_result",
+          [](SimulationState* self, const char* code) {
+            return self->loadCodeWithResult(self, code);
+          },
+          R"(Loads the given code into the simulation state and returns details.
+
+Args:
+    code (str): The code to load.
+
+Returns:
+    LoadResult: The structured load result.)")
       .def(
           "step_forward",
           [](SimulationState* self) { checkOrThrow(self->stepForward(self)); },

include/backend/dd/DDSimDebug.hpp

@@ -119,6 +119,22 @@ struct DDSimulationState {
    * @brief The code being executed, after preprocessing.
    */
   std::string processedCode;
+  /**
+   * @brief The last error message produced by the interface.
+   */
+  std::string lastErrorMessage;
+  /**
+   * @brief The last error detail produced by the interface.
+   */
+  std::string lastErrorDetail;
+  /**
+   * @brief The 1-based line of the last error, or 0 if unavailable.
+   */
+  size_t lastErrorLine = 0;
+  /**
+   * @brief The 1-based column of the last error, or 0 if unavailable.
+   */
+  size_t lastErrorColumn = 0;
   /**
    * @brief Indicates whether the debugger is ready to start simulation.
    */
@@ -280,6 +296,14 @@ Result ddsimInit(SimulationState* self);
  * @return The result of the operation.
  */
 Result ddsimLoadCode(SimulationState* self, const char* code);
+
+/**
+ * @brief Loads the given code into the simulation state and returns details.
+ * @param self The instance to load the code into.
+ * @param code The code to load.
+ * @return The structured load result.
+ */
+LoadResult ddsimLoadCodeWithResult(SimulationState* self, const char* code);
 /**
  * @brief Steps the simulation forward by one instruction.
  * @param self The instance to step forward.

include/backend/debug.h

@@ -38,6 +38,32 @@ extern "C" {
  */
 typedef struct SimulationStateStruct SimulationState;
 
+/**
+ * @brief Represents the structured result of a load operation.
+ */
+typedef struct {
+  /**
+   * @brief The result of the load operation.
+   */
+  Result result;
+  /**
+   * @brief The 1-based line of the error location, or 0 if unavailable.
+   */
+  size_t line;
+  /**
+   * @brief The 1-based column of the error location, or 0 if unavailable.
+   */
+  size_t column;
+  /**
+   * @brief The error detail text, or nullptr if unavailable.
+   */
+  const char* detail;
+  /**
+   * @brief The full error message, or nullptr if unavailable.
+   */
+  const char* message;
+} LoadResult;
+
 struct SimulationStateStruct {
   /**
    * @brief Initializes the simulation state.
@@ -54,6 +80,25 @@ struct SimulationStateStruct {
    */
   Result (*loadCode)(SimulationState* self, const char* code);
 
+  /**
+   * @brief Loads the given code into the simulation state and returns details.
+   * @param self The instance to load the code into.
+   * @param code The code to load.
+   * @return The structured load result.
+   */
+  LoadResult (*loadCodeWithResult)(SimulationState* self, const char* code);
+
+  /**
+   * @brief Gets the last error message from the interface.
+   *
+   * The returned pointer is owned by the implementation and remains valid
+   * until the next interface call that modifies the error state.
+   *
+   * @param self The instance to query.
+   * @return A null-terminated error message, or nullptr if none is available.
+   */
+  const char* (*getLastErrorMessage)(SimulationState* self);
+
   /**
    * @brief Steps the simulation forward by one instruction.
    * @param self The instance to step forward.

include/common/parsing/ParsingError.hpp

@@ -15,6 +15,8 @@
 
 #pragma once
 
+#include <cstddef>
+#include <optional>
 #include <stdexcept>
 #include <string>
 
@@ -23,13 +25,36 @@ namespace mqt::debugger {
 /**
  * @brief Represents an error that occurred during parsing.
  */
+struct ParsingErrorLocation {
+  size_t line;
+  size_t column;
+  std::string detail;
+};
+
 class ParsingError : public std::runtime_error {
 public:
   /**
    * @brief Constructs a new ParsingError with the given message.
    * @param msg The error message.
    */
   explicit ParsingError(const std::string& msg);
+
+  /**
+   * @brief Constructs a new ParsingError with a structured location.
+   * @param line The 1-based line number.
+   * @param column The 1-based column number.
+   * @param detail The error detail text.
+   */
+  ParsingError(size_t line, size_t column, std::string detail);
+
+  /**
+   * @brief Returns the location information if available.
+   * @return Pointer to the location info, or nullptr if absent.
+   */
+  const ParsingErrorLocation* location() const noexcept;
+
+private:
+  std::optional<ParsingErrorLocation> location_;
 };
 
 } // namespace mqt::debugger

python/mqt/debugger/__init__.py

@@ -18,6 +18,8 @@
     Diagnostics,
     ErrorCause,
     ErrorCauseType,
+    LoadResult,
+    Result,
     SimulationState,
     Statevector,
     Variable,
@@ -33,6 +35,8 @@
     "Diagnostics",
     "ErrorCause",
     "ErrorCauseType",
+    "LoadResult",
+    "Result",
     "SimulationState",
     "Statevector",
     "Variable",