feat(debugger): creating a very basic debugger, started by VM::showBacktraceWithException

Author: SuperFola

include/Ark/VM/Debugger.hpp

@@ -0,0 +1,52 @@
+/**
+ * @file Debugger.hpp
+ * @author Lexy Plateau (lexplt.dev@gmail.com)
+ * @brief Debugger used by the VM when an error or a breakpoint is reached
+ * @date 2026-01-12
+ *
+ * @copyright Copyright (c) 2026-01-12
+ *
+ */
+
+#ifndef ARK_VM_DEBUGGER_HPP
+#define ARK_VM_DEBUGGER_HPP
+
+#include <Ark/VM/ExecutionContext.hpp>
+
+#include <vector>
+#include <memory>
+
+namespace Ark::internal
+{
+    struct SavedState
+    {
+        std::size_t ip;
+        std::size_t pp;
+        uint16_t sp;
+        uint16_t fc;
+        std::vector<ScopeView> locals;
+        std::vector<std::shared_ptr<ClosureScope>> closure_scopes;
+    };
+
+    class Debugger
+    {
+    public:
+        /**
+         * @brief Create a new Debugger object
+         *
+         * @param context context from the VM before displaying a backtrace
+         */
+        explicit Debugger(const ExecutionContext& context);
+
+        void saveState(const ExecutionContext& context);
+
+        void resetContextToErrorState(ExecutionContext& context);
+
+        void run();
+
+    private:
+        std::vector<std::unique_ptr<SavedState>> m_states;
+    };
+}
+
+#endif  // ARK_VM_DEBUGGER_HPP

include/Ark/VM/VM.hpp

@@ -34,6 +34,7 @@
 #include <Ark/Utils/Literals.hpp>
 #include <Ark/VM/SharedLibrary.hpp>
 #include <Ark/VM/Value/Future.hpp>
+#include <Ark/VM/Debugger.hpp>
 
 namespace Ark
 {
@@ -175,6 +176,7 @@ namespace Ark
         std::mutex m_mutex, m_mutex_futures;
         std::vector<std::shared_ptr<internal::SharedLibrary>> m_shared_lib_objects;
         std::vector<std::unique_ptr<internal::Future>> m_futures;  ///< Storing the promises while we are resolving them
+        std::unique_ptr<internal::Debugger> m_debugger { nullptr };
 
         // a little trick for operator[] and for pop
         Value m_no_value = internal::Builtins::nil;
@@ -352,6 +354,8 @@ namespace Ark
 
         [[noreturn]] void throwArityError(std::size_t passed_arg_count, std::size_t expected_arg_count, internal::ExecutionContext& context);
 
+        void initDebugger(internal::ExecutionContext& context);
+
         void showBacktraceWithException(const std::exception& e, internal::ExecutionContext& context);
 
         /**
@@ -361,9 +365,9 @@ namespace Ark
          * @param pp
          * @return std::optional<InstLoc>
          */
-        std::optional<internal::InstLoc> findSourceLocation(std::size_t ip, std::size_t pp) const;
+        [[nodiscard]] std::optional<internal::InstLoc> findSourceLocation(std::size_t ip, std::size_t pp) const;
 
-        std::string debugShowSource() const;
+        [[nodiscard]] std::string debugShowSource() const;
 
         /**
          * @brief Display a backtrace when the VM encounter an exception

src/arkreactor/VM/Debugger.cpp

@@ -0,0 +1,45 @@
+#include <Ark/VM/Debugger.hpp>
+
+#include <fmt/core.h>
+
+namespace Ark::internal
+{
+    // TODO: Create a new context?
+    //       Creating a new context meaning modifying where the scope views points to,
+    //       because the underlying storage won't have the same address.
+    Debugger::Debugger(const ExecutionContext& context)
+    {
+        saveState(context);
+    }
+
+    void Debugger::saveState(const ExecutionContext& context)
+    {
+        m_states.emplace_back(
+            std::make_unique<SavedState>(
+                context.ip,
+                context.pp,
+                context.sp,
+                context.fc,
+                context.locals,
+                context.stacked_closure_scopes));
+    }
+
+    void Debugger::resetContextToErrorState(ExecutionContext& context)
+    {
+        const auto& [ip, pp, sp, fc, locals, closure_scopes] = *m_states.back();
+        context.locals = locals;
+        context.stacked_closure_scopes = closure_scopes;
+        context.ip = ip;
+        context.pp = pp;
+        context.sp = sp;
+        context.fc = fc;
+
+        m_states.pop_back();
+    }
+
+    void Debugger::run()
+    {
+        // TODO: create a shell
+        fmt::println("debugger running");
+    }
+}

src/arkreactor/VM/VM.cpp

@@ -918,7 +918,7 @@ namespace Ark
                                     args.push_back(*popAndResolveAsPtr(context));
                                 throw types::TypeCheckingError(
                                     "append",
-                                    { { types::Contract { { types::Typedef("list", ValueType::List), types::Typedef("value", ValueType::Any, /* variadic= */ true) } } } },
+                                    { { types::Contract { { types::Typedef("list", ValueType::List), types::Typedef("value", ValueType::Any, /* is_variadic= */ true) } } } },
                                     args);
                             }
 
@@ -1188,8 +1188,11 @@ namespace Ark
                     {
                         {
                             const Value cond = *popAndResolveAsPtr(context);
-                            if (cond == Builtins::trueSym)  // todo: trigger debugger
-                            {}
+                            if (cond == Builtins::trueSym)
+                            {
+                                initDebugger(context);
+                                m_debugger->run();
+                            }
                         }
                         DISPATCH();
                     }
@@ -2254,13 +2257,24 @@ namespace Ark
                 fmt::join(arg_names, " ")));
     }
 
-    void VM::showBacktraceWithException(const std::exception& e, internal::ExecutionContext& context)
+    void VM::initDebugger(internal::ExecutionContext& context)
+    {
+        if (!m_debugger)
+            m_debugger = std::make_unique<Debugger>(context);
+        else
+            m_debugger->saveState(context);
+    }
+
+    void VM::showBacktraceWithException(const std::exception& e, ExecutionContext& context)
     {
         std::string text = e.what();
         if (!text.empty() && text.back() != '\n')
             text += '\n';
         fmt::println("{}", text);
 
+        if (m_state.m_features & FeatureVMDebugger)
+            initDebugger(context);
+
         const std::size_t saved_ip = context.ip;
         const std::size_t saved_pp = context.pp;
         const uint16_t saved_sp = context.sp;
@@ -2274,9 +2288,10 @@ namespace Ark
             fmt::styled(saved_pp, fmt::fg(fmt::color::green)),
             fmt::styled(saved_sp, fmt::fg(fmt::color::yellow)));
 
-        if (m_state.m_features & FeatureVMDebugger)
+        if (m_debugger)
         {
-            // TODO: launch debugger
+            m_debugger->resetContextToErrorState(context);
+            m_debugger->run();
         }
 
 #ifdef FUZZING_BUILD_MODE_UNSAFE_FOR_PRODUCTION