openscad-cpp-evaluator 0.3.0__tar.gz → 0.4.0__tar.gz

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/CLAUDE.md

@@ -241,15 +241,32 @@ Roman:style=Bold"`) silently gets Liberation Sans instead under this default pro
 path needed in this repo: the fix is a Qt host application supplying its own `FontProvider`, which
 is exactly what the injection seam exists for.
 
-**Debugger/profiler, Phase 9 (the last phase)**: `checkDebug()` fires from exactly one call site
-(`evalChildren`'s `runAll`, plus one explicit call each at user-function/function-literal body entry
-and inside `breakpoint()`'s resolve) rather than the reference's several dozen `_check_debug` call
-sites scattered across nearly every statement/expression-eval function — a deliberate scope
-reduction (see `debug_hooks.hpp`'s `DebugHookFn` doc comment for the full reasoning): the reference's
-extra sites exist for `expr_level` sub-statement stepping (individual list-comprehension clauses,
-ternary branches) that neither this port's own `debug_repl.cpp` REPL nor the reference's own
-`_debug_repl.py` REPL ever actually uses (both only ever pause/step at statement granularity in
-practice). Verified this is a faithful, not just simplified, port by running an *identical*
+**Debugger/profiler, Phase 9 (the last phase)**: `checkDebug()` fires at **full parity with the
+reference's `_check_debug` call sites** — the statement checkpoint in `evalChildren`'s `runAll`,
+user-function/function-literal body entry, `breakpoint()`'s resolve, *and* the reference's
+sub-statement sites: if/else branch entry (`evalStatement`), for-loop per-variable bindings and
+per-iteration body entry (`evalFor`), `intersection_for` body entry, statement- and
+expression-form `let()` assignments, expression-form `echo()`/`assert()`, ternary
+condition/chosen-branch, every list-comprehension clause including the C-style `for`
+(`evalListElement`), modifier-wrapped children (`evalModifier`), and user function/function-literal
+call sites (`evalFunctionCall`, plus their duplicates in `simplifyTailStep` so a tail chain isn't
+debug-invisible). Each carries the reference's `expr_level` flag, threaded all the way through
+`DebugHookFn` and the nanobind trampoline. `expr_depth` is *not* tracked (hardcoded 0 through the
+Python surface) — no consumer reads it.
+
+An earlier revision of this file argued the sub-statement sites were unnecessary because no REPL
+steps at that granularity. That was wrong: BelfrySCAD's debugger UI consumes them, and one case was
+an outright bug — a C-style `for` *inside a list comprehension* got zero debug checks anywhere,
+so a breakpoint set on it never fired. Two consequences of full parity worth knowing:
+`useBytecodeVm()` returns false whenever a debug hook is installed (compiled chunks flatten away the
+AST nodes these checkpoints hang off, so debugging always takes the interpreter path), and
+`evalChildren` deliberately skips its own check for `ModularLet` — the reference's
+`_eval_statement_impl` skips it too, pausing on the let's assignments instead. Parity is verified
+test-by-test in `tests/test_debug_hooks.cpp`'s `DebugHooksParity` suite, whose expected
+`(line, expr_level, forced)` sequences were captured by running the Python reference over the same
+sources, not written down from this port's own output.
+
+The port was also verified end to end by running an *identical*
 `--debug` session (same script, same `break`/`run`/`print`/`continue`/`step`/`backtrace`/`set`
 sequence) against both this port's CLI and the real Python reference's own `openscad-evaluator
 --debug` side by side: transcripts matched exactly, **including** an unexpected extra pause neither

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openscad_cpp_evaluator
-Version: 0.3.0
+Version: 0.4.0
 Summary: C++ OpenSCAD evaluator with Python bindings
 Author: NeuSCAD Contributors
 License-Expression: MIT

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/bindings/module.cpp

@@ -313,13 +313,21 @@ nb::object generatePartialTrampoline(const GeneratePartialFn& generatePartial) {
 }
 
 // Trampoline: C++ debug hook -> the Python DebugSession hook. Runs with the
-// GIL held (reacquired by the caller). `getFrame`/`callStack`/`generatePartial`
-// are valid only for this synchronous call, so the get_frames/generate_partial
+// (origin, line) targets children()/children(N) might forward control to
+// from the just-checked debug-hook node, for the "step to child" command.
+// See Evaluator::lastChildrenPositions()'s own doc comment: valid only
+// synchronously within the current hook call, same as get_frames.
+using GetChildrenPositionsFn = std::function<const std::optional<std::vector<std::pair<std::string, int>>>&()>;
+
+// GIL held (reacquired by the caller). `getFrame`/`callStack`/`generatePartial`/
+// `getChildrenPositions` are valid only for this synchronous call, so their
 // closures are only ever invoked from within the Python hook, before it returns.
-oscadeval::DebugAction callPyDebugHook(nb::handle hook, int line, int depth, bool forced, const std::string& origin,
+oscadeval::DebugAction callPyDebugHook(nb::handle hook, int line, int depth, bool forced, bool exprLevel,
+                                        const std::string& origin,
                                         const std::vector<oscadeval::CallStackFrame>& callStack,
                                         const oscadeval::DebugFramesFn& getFrame,
-                                        const GeneratePartialFn& generatePartial) {
+                                        const GeneratePartialFn& generatePartial,
+                                        const GetChildrenPositionsFn& getChildrenPositions) {
     auto getFramesPy = nb::cpp_function([&callStack, &getFrame]() -> nb::object {
         std::vector<oscadeval::DebugFrame> frames = getFrame();
         nb::list allFrameLocals;
@@ -335,10 +343,21 @@ oscadeval::DebugAction callPyDebugHook(nb::handle hook, int line, int depth, boo
         return nb::make_tuple(nb::make_tuple(lastLocals, allFrameLocals), callStackToPy(callStack));
     });
     nb::object generatePartialPy = generatePartialTrampoline(generatePartial);
+    auto getChildrenPositionsPy = nb::cpp_function([&getChildrenPositions]() -> nb::object {
+        const std::optional<std::vector<std::pair<std::string, int>>>& positions = getChildrenPositions();
+        if (!positions) return nb::none();
+        nb::list out;
+        for (const auto& [origin, line] : *positions) out.append(nb::make_tuple(origin, line));
+        return out;
+    });
 
-    nb::object ret = hook(line, depth, nb::arg("forced") = forced, nb::arg("expr_level") = false,
+    // expr_depth stays hardcoded at 0 -- this port deliberately doesn't
+    // track the reference's _expr_depth counter (no consumer reads it);
+    // expr_level, which consumers do read, is the real threaded value.
+    nb::object ret = hook(line, depth, nb::arg("forced") = forced, nb::arg("expr_level") = exprLevel,
                           nb::arg("expr_depth") = 0, nb::arg("origin") = origin, nb::arg("get_frames") = getFramesPy,
-                          nb::arg("generate_partial") = generatePartialPy);
+                          nb::arg("generate_partial") = generatePartialPy,
+                          nb::arg("get_children_positions") = getChildrenPositionsPy);
     nb::tuple t = nb::cast<nb::tuple>(ret);
     oscadeval::DebugAction action;
     action.stop = (nb::cast<std::string>(t[0]) == "stop");
@@ -399,12 +418,17 @@ nb::object debugEvaluate(const std::string& path, nb::dict viewportParams, nb::c
         GeneratePartialFn generatePartial = [&evPtr]() -> std::vector<oscadeval::ColoredBody> {
             return evPtr->generatePartialTree();
         };
+        GetChildrenPositionsFn getChildrenPositions =
+            [&evPtr]() -> const std::optional<std::vector<std::pair<std::string, int>>>& {
+            return evPtr->lastChildrenPositions();
+        };
         oscadeval::DebugHooks hooks;
-        hooks.debugHook = [&](int line, int depth, bool forced, const std::string& origin,
+        hooks.debugHook = [&](int line, int depth, bool forced, bool exprLevel, const std::string& origin,
                               const std::vector<oscadeval::CallStackFrame>& cs,
                               const oscadeval::DebugFramesFn& gf) -> oscadeval::DebugAction {
             nb::gil_scoped_acquire g;
-            return callPyDebugHook(debugHook, line, depth, forced, origin, cs, gf, generatePartial);
+            return callPyDebugHook(debugHook, line, depth, forced, exprLevel, origin, cs, gf, generatePartial,
+                                    getChildrenPositions);
         };
         hooks.errorBreak = [&](int line, const std::string& header, const std::string& origin,
                                const std::vector<oscadeval::CallStackFrame>& cs, const oscadeval::DebugFramesFn& gf) {

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/examples/minimal_debugger.cpp

@@ -46,7 +46,7 @@ std::string fmtLocals(const std::unordered_map<std::string, Value>& locals) {
 void traceEveryStatement() {
     std::cout << "1. trace every statement:\n";
     DebugHooks hooks;
-    hooks.debugHook = [](int line, int depth, bool, const std::string&, const std::vector<CallStackFrame>&,
+    hooks.debugHook = [](int line, int depth, bool, bool, const std::string&, const std::vector<CallStackFrame>&,
                           const DebugFramesFn& getFrame) {
         std::vector<DebugFrame> frames = getFrame();
         DebugFrame frame = frames.empty() ? DebugFrame{} : frames.front();
@@ -69,7 +69,7 @@ void stopAtBreakpoint() {
     constexpr int kBreakLine = 3; // the `translate(...) sphere(...)` statement
 
     DebugHooks hooks;
-    hooks.debugHook = [](int line, int, bool, const std::string&, const std::vector<CallStackFrame>&, const DebugFramesFn&) {
+    hooks.debugHook = [](int line, int, bool, bool, const std::string&, const std::vector<CallStackFrame>&, const DebugFramesFn&) {
         DebugAction action;
         if (line == kBreakLine) {
             std::cout << "  breakpoint hit at line " << line << "\n";
@@ -97,7 +97,7 @@ void stopAtBreakpoint() {
 void overrideVariableViaMods() {
     std::cout << "3. override a variable via mods:\n";
     DebugHooks hooks;
-    hooks.debugHook = [](int line, int, bool, const std::string&, const std::vector<CallStackFrame>&, const DebugFramesFn&) {
+    hooks.debugHook = [](int line, int, bool, bool, const std::string&, const std::vector<CallStackFrame>&, const DebugFramesFn&) {
         DebugAction action;
         if (line == 2) action.mods["width"] = Value{2.0}; // about to run `cube([width, width, width])`
         return action;

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/include/openscad_cpp_evaluator/debug_hooks.hpp

@@ -86,25 +86,31 @@ inline constexpr const char* kDebuggingStoppedMessage = "Debugging stopped.";
 // genuine (non-debugger-triggered) EvalError leaves it at.
 enum class PostRunAction { None, Stopped, Restart, Quit };
 
-// Called at (approximately) every top-level statement in every block --
-// see Evaluator::evalChildren's single call site for the exact mechanism,
-// and its own comment for why this port checks at statement granularity
-// only, not the reference's additional expr_level sub-expression checks
-// (list-comprehension clauses, ternary branches, ...): those exist in the
-// reference to let a debugger single-step through individual expression
-// evaluation, which no consumer of this seam (debug_repl.cpp's REPL,
-// nor a plausible future GUI one) actually needs -- "pause on any
-// statement, inspect locals, set a breakpoint" is fully served by
-// statement-level granularity alone, at a small fraction of the
-// reference's own call-site count. Also called once, with `forced=true`,
-// right before evaluating a user function/function-literal's body
-// expression (functions have no statement-level granularity to hang a
-// hook off otherwise) and by breakpoint() (forced=true, unconditionally,
-// matching the reference's own _check_debug(..., forced=True) call).
+// Called at every point the Python reference calls _check_debug: every
+// top-level statement in every block (Evaluator::evalChildren's single
+// statement checkpoint), plus the reference's finer-grained sub-statement
+// sites -- ternary condition and chosen branch, if/else branch entry,
+// for-loop per-variable bindings and per-iteration body entry,
+// statement- and expression-form let() assignments, expression-form
+// echo()/assert(), every list-comprehension clause (if / if-else / let /
+// each / for / C-style-for, plus bare elements), modifier-wrapped
+// children, and user function / function-literal call sites. Also called
+// once right before evaluating a user function/function-literal's body
+// expression, and by breakpoint() (forced=true, unconditionally, matching
+// the reference's own _check_debug(..., forced=True) call).
+//
+// `exprLevel` mirrors the reference's `expr_level` keyword exactly: true
+// for the sub-expression markers a debugger should NOT treat as a
+// steppable/breakpointable statement (a chosen ternary or if branch, a
+// for-loop body entry, a list-comprehension body element, a C-style-for
+// condition re-check). Both this port's own debug_repl.cpp and the
+// reference's _debug_repl.py gate every step/breakpoint decision on
+// `!exprLevel`, while still pausing unconditionally on `forced`.
+//
 // `depth` is the live user-call-stack depth (Evaluator::callStack_.size())
 // at the pause point. Mirrors Evaluator._check_debug/the debug_hook
 // callback contract.
-using DebugHookFn = std::function<DebugAction(int line, int depth, bool forced, const std::string& origin,
+using DebugHookFn = std::function<DebugAction(int line, int depth, bool forced, bool exprLevel, const std::string& origin,
                                                const std::vector<CallStackFrame>& callStack, const DebugFramesFn& getFrame)>;
 
 // Called from Evaluator::error() right before it throws, if set -- gives a

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/include/openscad_cpp_evaluator/debug_repl.hpp

@@ -128,7 +128,7 @@ public:
     bool runPrompt();
 
     // Wire these three into Evaluator's DebugHooks (see debug_hooks.hpp).
-    DebugAction debugHook(int line, int depth, bool forced, const std::string& origin,
+    DebugAction debugHook(int line, int depth, bool forced, bool exprLevel, const std::string& origin,
                            const std::vector<CallStackFrame>& callStack, const DebugFramesFn& getFrame);
     void errorBreak(int line, const std::string& header, const std::string& origin, const std::vector<CallStackFrame>& callStack,
                      const DebugFramesFn& getFrame);

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/include/openscad_cpp_evaluator/evaluator.hpp

@@ -323,13 +323,16 @@ public:
     // filtering, which lives entirely in the injected hook, not here) --
     // it's simply passed through so the hook itself can distinguish an
     // unconditional breakpoint()/function-entry pause from a normal
-    // statement-boundary check. Public: called from evalChildren() (every
-    // ordinary statement), evalUserFunction()/evalFunctionLiteral() (function
-    // body entry), and builtins/control.cpp's resolveBreakpoint (a free
-    // function). See debug_hooks.hpp's DebugHookFn doc comment for the
-    // exact statement-level-only scope decision. Mirrors
-    // Evaluator._check_debug.
-    void checkDebug(const oscad::ASTNode& node, EvalContext& ctx, bool forced = false);
+    // statement-boundary check. `exprLevel=true` marks a sub-statement
+    // (expression-granularity) checkpoint that a stepping debugger should
+    // not treat as a statement boundary -- see debug_hooks.hpp's
+    // DebugHookFn doc comment for the full list of call sites and the
+    // exprLevel contract. Public: called from evalChildren() (every
+    // ordinary statement), evalUserFunction()/evalFunctionLiteral()
+    // (function body entry), and builtins/control.cpp's
+    // resolveBreakpoint/resolveIntersectionFor (free functions). Mirrors
+    // Evaluator._check_debug, including its parameter defaults.
+    void checkDebug(const oscad::ASTNode& node, EvalContext& ctx, bool forced = false, bool exprLevel = false);
 
     // (origin, line) for each top-level, non-declaration child of the
     // node checkDebug() was just called with -- i.e., if that node is a
@@ -789,6 +792,17 @@ private:
     // strategy this enables).
     static bool bytecodeVmEnabled();
 
+    // Per-evaluator gate actually consulted before using a compiled chunk.
+    // Compiled bytecode has no per-AST-node debug checkpoints (its whole
+    // point is to flatten those nodes away), so a function body run on the
+    // VM would silently skip every checkDebug() call site the interpreter
+    // path makes -- ternary branches, let()/echo()/assert() expression
+    // forms, list-comprehension clauses, nested call sites. Debugging
+    // therefore always takes the interpreter path, where the port matches
+    // the reference's _check_debug placement exactly. Costs nothing when
+    // no debugger is attached, which is every non-debug render.
+    bool useBytecodeVm() const { return !debugHooks_.debugHook && bytecodeVmEnabled(); }
+
     // -- Profiling (Phase 9) --------------------------------------------
 
     // (kind, name, callOrigin, callLine) -- the exact call-site identity a

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "scikit_build_core.build"
 
 [project]
 name = "openscad_cpp_evaluator"
-version = "0.3.0"
+version = "0.4.0"
 description = "C++ OpenSCAD evaluator with Python bindings"
 readme = "README.md"
 requires-python = ">=3.12"

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/src/builtins/control.cpp

@@ -112,6 +112,11 @@ CSGParams resolveIntersectionFor(Evaluator& ev, const oscad::ModularIntersection
 
     std::function<void(size_t, EvalContext&)> recurse = [&](size_t depth, EvalContext& parentCtx) {
         if (depth == varSeqs.size()) {
+            // One body-entry marker per full cartesian-product iteration
+            // and nothing per individual variable binding (unlike
+            // evalFor) -- mirrors _resolve_intersection_for's single
+            // `_check_debug(body_node[0], loop_ctx, expr_level=True)`.
+            if (!bodyNodes.empty()) ev.checkDebug(*bodyNodes.front(), parentCtx, /*forced=*/false, /*exprLevel=*/true);
             const size_t before = ev.currentTreeFrameSize();
             ev.evalChildren(bodyNodes, parentCtx);
             const size_t after = ev.currentTreeFrameSize();

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/src/csg_resolve.cpp

@@ -140,6 +140,16 @@ void Evaluator::evalModifier(const oscad::ModuleInstantiation& child, const osca
     // always empty (role tagging happens entirely in the matching
     // generate function -- generateHighlight/Background/ShowOnly).
     buildTreeNode(kind, wrapperNode, [&]() {
+        // The wrapped child gets its own statement-level stop, in addition
+        // to the modifier node's (which evalChildren already fired before
+        // dispatching here) -- so `#cube(1);` pauses twice, like the
+        // reference. There, _resolve_modifier_child has no _check_debug of
+        // its own: it calls _eval_statement(node.child, ctx), and _that_
+        // dispatcher independently checks every _TREE_NODE_TYPES node it
+        // is handed. This port's evalStatement has no such blanket check
+        // (evalChildren owns it), so the equivalent stop is made explicit
+        // here.
+        checkDebug(child, ctx);
         evalStatement(child, ctx);
         return CSGParams{};
     });

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/src/debug/debug_repl.cpp

@@ -425,18 +425,24 @@ bool DebugRepl::runPrompt() {
     }
 }
 
-DebugAction DebugRepl::debugHook(int line, int depth, bool forced, const std::string& origin,
+DebugAction DebugRepl::debugHook(int line, int depth, bool forced, bool exprLevel, const std::string& origin,
                                   const std::vector<CallStackFrame>& callStack, const DebugFramesFn& getFrame) {
     if (quit_) return DebugAction{true, {}};
 
+    // Every step/breakpoint/first-statement decision below is gated on
+    // !exprLevel -- a sub-expression marker (chosen ternary/if branch,
+    // loop body entry, list-comprehension body element) is not a statement
+    // this REPL steps to or breaks on. Only `forced` (breakpoint()) and an
+    // async pause request ignore it. Mirrors _debug_repl.py's debug_hook
+    // exactly, clause for clause.
     const std::string resolved = resolveOrigin(origin);
     bool stepHit = false;
     if (stepCmd_ == "over") {
-        stepHit = depth <= stepDepth_ && resolved == stepOrigin_ && line != stepLine_;
+        stepHit = depth <= stepDepth_ && resolved == stepOrigin_ && line != stepLine_ && !exprLevel;
     } else if (stepCmd_ == "into") {
-        stepHit = line != stepLine_ || resolved != stepOrigin_;
+        stepHit = (line != stepLine_ || resolved != stepOrigin_) && !exprLevel;
     } else if (stepCmd_ == "out") {
-        stepHit = depth < stepDepth_;
+        stepHit = depth < stepDepth_ && !exprLevel;
     } else if (stepCmd_ == "to_child") {
         // Pause the first time control reaches one of the paused call's
         // own children (wherever children()/children(N) forwards to
@@ -444,7 +450,7 @@ DebugAction DebugRepl::debugHook(int line, int depth, bool forced, const std::st
         // back to the same "call returned" safety net step-out uses, so
         // this can never hang. Mirrors BelfrySCAD's DebugSession::
         // _make_hook exactly.
-        stepHit = stepToChildTargets_.count({resolved, line}) > 0 || depth < stepDepth_;
+        stepHit = !exprLevel && (stepToChildTargets_.count({resolved, line}) > 0 || depth < stepDepth_);
     }
 
     // Read-and-clear, same as BelfrySCAD's own DebugSession.pause()/
@@ -454,8 +460,8 @@ DebugAction DebugRepl::debugHook(int line, int depth, bool forced, const std::st
     // immediate re-pause; a harmless quirk, not a hang or crash.
     const bool pauseRequested = pauseRequested_.exchange(false, std::memory_order_relaxed);
 
-    const bool shouldPause = forced || pauseRequested || (breakOnFirst_ && resolved == sourcePath_) ||
-                              breakpoints_[resolved].count(line) > 0 || stepHit;
+    const bool shouldPause = forced || pauseRequested || (breakOnFirst_ && !exprLevel && resolved == sourcePath_) ||
+                              (breakpoints_[resolved].count(line) > 0 && !exprLevel) || stepHit;
     if (!shouldPause) return DebugAction{};
 
     breakOnFirst_ = false;

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/src/debug_profile.cpp

@@ -74,14 +74,14 @@ std::vector<DebugFrame> Evaluator::buildDebugFrames(const EvalContext* ctx) cons
     return frames;
 }
 
-void Evaluator::checkDebug(const oscad::ASTNode& node, EvalContext& ctx, bool forced) {
+void Evaluator::checkDebug(const oscad::ASTNode& node, EvalContext& ctx, bool forced, bool exprLevel) {
     if (!debugHooks_.debugHook) return;
     const oscad::Position& pos = node.position();
     const int depth = static_cast<int>(callStack_.size());
     const DebugFramesFn getFrame = [this, &ctx]() { return buildDebugFrames(&ctx); };
     lastChildrenPositions_ = childStatementPositions(node);
 
-    DebugAction action = debugHooks_.debugHook(pos.line, depth, forced, pos.origin, callStack_, getFrame);
+    DebugAction action = debugHooks_.debugHook(pos.line, depth, forced, exprLevel, pos.origin, callStack_, getFrame);
     for (auto& [k, v] : action.mods) ctx.let_->set(k, v);
     if (action.stop) throw EvalError(kDebuggingStoppedMessage);
 }

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/src/expr_eval.cpp

@@ -119,6 +119,11 @@ Value Evaluator::evalIdentifier(const std::string& name, const oscad::Position*
 
 // -- List comprehensions ----------------------------------------------
 
+// Debug checkpoints below mirror the reference's _eval_list_comp AND its
+// near-duplicate twin _eval_list_comp_body (both dispatch over the same
+// ListComp* kinds with identical _check_debug placement; this port folds
+// them into this one function plus evalListCompBody's ListComprehension
+// early-out, so one set of calls covers both).
 void Evaluator::evalListElement(const oscad::ASTNode& elem, EvalContext& ctx, std::vector<Value>& out) {
     switch (elem.kind()) {
         case oscad::NodeKind::ListCompFor: {
@@ -147,6 +152,11 @@ void Evaluator::evalListElement(const oscad::ASTNode& elem, EvalContext& ctx, st
                 for (const Value& val : pairs[depth].values) {
                     EvalContext childCtx = parentCtx.letChildCtx();
                     childCtx.let_->set(pairs[depth].name, val);
+                    // Per-binding stop, same shape as evalFor's -- but with
+                    // NO separate body-entry marker at depth == pairs.size()
+                    // (_eval_listcomp_for has none; the body's own element
+                    // check below supplies the expr-level stop instead).
+                    checkDebug(*n.assignments[depth], childCtx);
                     recurse(depth + 1, childCtx);
                 }
             };
@@ -154,47 +164,73 @@ void Evaluator::evalListElement(const oscad::ASTNode& elem, EvalContext& ctx, st
             return;
         }
         case oscad::NodeKind::ListCompCFor: {
+            // Stop order per _eval_listcomp_cfor, exactly:
+            //   init(s) -> [cond(true) -> body -> incr(s)]* -> cond(false)
+            // The condition is checked (expr-level) on EVERY pass including
+            // the final false one that ends the loop; body entry uses the
+            // whole ListCompCFor node, not the body expression.
             auto& n = static_cast<const oscad::ListCompCFor&>(elem);
             EvalContext loopCtx = ctx.letChildCtx();
-            for (const auto& assign : n.inits) loopCtx.let_->set(assign->name->name, evalExpr(*assign->expr, loopCtx));
+            for (const auto& assign : n.inits) {
+                checkDebug(*assign, loopCtx);
+                loopCtx.let_->set(assign->name->name, evalExpr(*assign->expr, loopCtx));
+            }
 
             const bool isNestedLc = (n.body->kind() == oscad::NodeKind::ListComprehension);
             constexpr int kMaxCForIterations = 1'000'000;
             int iterations = 0;
-            while (truthy(evalExpr(*n.condition, loopCtx))) {
+            while (true) {
+                checkDebug(*n.condition, loopCtx, /*forced=*/false, /*exprLevel=*/true);
+                if (!truthy(evalExpr(*n.condition, loopCtx))) break;
                 ++iterations;
                 if (iterations > kMaxCForIterations) {
                     error("C-style for loop exceeded maximum iteration count", n);
                 }
+                checkDebug(n, loopCtx);
                 if (isNestedLc) {
                     out.push_back(evalListLiteral(static_cast<const oscad::ListComprehension&>(*n.body), loopCtx));
                 } else {
                     appendAll(out, evalListCompBody(*n.body, loopCtx));
                 }
-                for (const auto& assign : n.incrs) loopCtx.let_->set(assign->name->name, evalExpr(*assign->expr, loopCtx));
+                for (const auto& assign : n.incrs) {
+                    checkDebug(*assign, loopCtx);
+                    loopCtx.let_->set(assign->name->name, evalExpr(*assign->expr, loopCtx));
+                }
             }
             return;
         }
         case oscad::NodeKind::ListCompIf: {
             auto& n = static_cast<const oscad::ListCompIf&>(elem);
-            if (truthy(evalExpr(*n.condition, ctx))) appendAll(out, evalListCompBody(*n.trueExpr, ctx));
+            checkDebug(n, ctx);
+            if (truthy(evalExpr(*n.condition, ctx))) {
+                checkDebug(*n.trueExpr, ctx, /*forced=*/false, /*exprLevel=*/true);
+                appendAll(out, evalListCompBody(*n.trueExpr, ctx));
+            }
             return;
         }
         case oscad::NodeKind::ListCompIfElse: {
             auto& n = static_cast<const oscad::ListCompIfElse&>(elem);
+            checkDebug(n, ctx);
             const oscad::ASTNode& branch = truthy(evalExpr(*n.condition, ctx)) ? *n.trueExpr : *n.falseExpr;
+            checkDebug(branch, ctx, /*forced=*/false, /*exprLevel=*/true);
             appendAll(out, evalListCompBody(branch, ctx));
             return;
         }
         case oscad::NodeKind::ListCompLet: {
             auto& n = static_cast<const oscad::ListCompLet&>(elem);
             EvalContext letCtx = ctx.letChildCtx();
-            for (const auto& assign : n.assignments) bindLetName(letCtx, assign->name->name, evalExpr(*assign->expr, letCtx));
+            // Per-assignment stops only -- no expr-level body marker here,
+            // unlike the if/if-else/each clauses (matches the reference).
+            for (const auto& assign : n.assignments) {
+                checkDebug(*assign, letCtx);
+                bindLetName(letCtx, assign->name->name, evalExpr(*assign->expr, letCtx));
+            }
             appendAll(out, evalListCompBody(*n.body, letCtx));
             return;
         }
         case oscad::NodeKind::ListCompEach: {
             auto& n = static_cast<const oscad::ListCompEach&>(elem);
+            checkDebug(n, ctx, /*forced=*/false, /*exprLevel=*/true);
             const oscad::ASTNode& inner = *n.body;
             if (isListCompClauseKind(inner.kind())) {
                 for (const Value& item : evalListCompBody(inner, ctx)) appendEachInto(out, item);
@@ -204,6 +240,7 @@ void Evaluator::evalListElement(const oscad::ASTNode& elem, EvalContext& ctx, st
             return;
         }
         default:
+            checkDebug(elem, ctx, /*forced=*/false, /*exprLevel=*/true);
             out.push_back(evalExpr(static_cast<const oscad::Expression&>(elem), ctx));
             return;
     }
@@ -265,6 +302,9 @@ Value Evaluator::evalLetExpr(const oscad::LetOp& node, EvalContext& ctx) {
         // Unlike the *statement* form (evalLetBlock), which does not --
         // see that method's own doc comment for why this isn't a copy/paste
         // mistake in one direction or the other.
+        // Checked against childCtx (not ctx) -- _expr_let does the same,
+        // the mirror image of _eval_let_block's `_check_debug(assign, ctx)`.
+        checkDebug(*assign, childCtx);
         Value v = evalExpr(*assign->expr, childCtx);
         bindLetName(childCtx, assign->name->name, v);
     }
@@ -272,6 +312,7 @@ Value Evaluator::evalLetExpr(const oscad::LetOp& node, EvalContext& ctx) {
 }
 
 Value Evaluator::evalEchoExpr(const oscad::EchoOp& node, EvalContext& ctx) {
+    checkDebug(node, ctx); // _expr_echo
     doEcho(node.arguments, ctx);
     return evalExpr(*node.body, ctx);
 }
@@ -281,6 +322,7 @@ Value Evaluator::evalAssertExpr(const oscad::AssertOp& node, EvalContext& ctx) {
     // arguments via getArg()/CallArgs, the expression form indexes raw
     // arguments positionally -- mirrors the reference's _expr_assert
     // exactly (`raw[0].expr`/`raw[1].expr`, not _get_arg).
+    checkDebug(node, ctx); // _expr_assert, before the condition is evaluated
     const auto& raw = node.arguments;
     const bool condition = raw.empty() || truthy(evalExpr(*argExpr(*raw[0]), ctx));
     if (!condition) {
@@ -431,8 +473,14 @@ Value Evaluator::evalExpr(const oscad::Expression& node, EvalContext& ctx) {
         }
 
         case NodeKind::TernaryOp: {
+            // Mirrors _expr_ternary: a statement-level stop on the whole
+            // ternary before the condition runs, then an expr-level one on
+            // whichever branch was chosen, before evaluating it.
             auto& n = static_cast<const oscad::TernaryOp&>(node);
-            return truthy(evalExpr(*n.condition, ctx)) ? evalExpr(*n.trueExpr, ctx) : evalExpr(*n.falseExpr, ctx);
+            checkDebug(n, ctx);
+            const oscad::Expression& branch = truthy(evalExpr(*n.condition, ctx)) ? *n.trueExpr : *n.falseExpr;
+            checkDebug(branch, ctx, /*forced=*/false, /*exprLevel=*/true);
+            return evalExpr(branch, ctx);
         }
 
         case NodeKind::BitwiseOrOp: {

{openscad_cpp_evaluator-0.3.0 → openscad_cpp_evaluator-0.4.0}/src/stmt_eval.cpp

@@ -95,12 +95,22 @@ void Evaluator::evalFor(const oscad::ModularFor& node, EvalContext& ctx) {
     // `let_`.
     std::function<void(size_t, EvalContext&)> recurse = [&](size_t depth, EvalContext& parentCtx) {
         if (depth == pairs.size()) {
+            // Per-full-iteration "entering the body" marker, separate from
+            // (and before) the body's own per-statement checks in
+            // evalChildren -- mirrors _eval_for's
+            // `_check_debug(node.body[0], parent_ctx, expr_level=True)`.
+            if (!bodyNodes.empty()) checkDebug(*bodyNodes.front(), parentCtx, /*forced=*/false, /*exprLevel=*/true);
             evalChildren(bodyNodes, parentCtx);
             return;
         }
         for (const Value& val : pairs[depth].values) {
             EvalContext childCtx = parentCtx.childCtx(nullptr, std::nullopt, ctx.childrenNodes, ctx.childrenCallerCtx);
             childCtx.let_->set(pairs[depth].name, val);
+            // One statement-level stop per (bound-so-far) combination, on
+            // the loop-variable assignment itself -- so a breakpoint set
+            // directly on an `i=[0:2],`/`j=[0:1]` line fires. Mirrors
+            // _eval_for's `_check_debug(assign_node, child)`.
+            checkDebug(*node.assignments[depth], childCtx);
             recurse(depth + 1, childCtx);
         }
     };
@@ -119,6 +129,9 @@ void Evaluator::evalLetBlock(const oscad::ModularLet& node, EvalContext& ctx) {
     // _eval_let_block, not an oversight -- it evaluates every RHS against
     // `ctx` in the loop, only ever writing into `child_ctx`.
     for (const auto& assign : node.assignments) {
+        // Checked against the ORIGINAL ctx (like the RHS eval below), not
+        // childCtx -- mirrors _eval_let_block's `_check_debug(assign, ctx)`.
+        checkDebug(*assign, ctx);
         Value v = evalExpr(*assign->expr, ctx);
         const std::string& name = assign->name->name;
         if (!name.empty() && name[0] == '$') {
@@ -163,18 +176,25 @@ void Evaluator::evalStatement(const oscad::ASTNode& node, EvalContext& ctx) {
         case oscad::NodeKind::ModularIntersectionFor:
             evalIntersectionForNode(static_cast<const oscad::ModularIntersectionFor&>(node), ctx);
             return;
+        // Both if-forms fire a branch-entry marker after the condition and
+        // before the branch's own per-statement checks, on the branch's
+        // first statement (or the if node itself for an empty branch) --
+        // mirrors _eval_statement_impl's
+        // `_check_debug(branch[0] if branch else node, ctx, expr_level=True)`.
         case oscad::NodeKind::ModularIf: {
             auto& n = static_cast<const oscad::ModularIf&>(node);
-            if (truthy(evalExpr(*n.condition, ctx))) evalChildren(n.trueBranch, ctx);
+            if (truthy(evalExpr(*n.condition, ctx))) {
+                checkDebug(n.trueBranch.empty() ? node : *n.trueBranch.front(), ctx, /*forced=*/false,
+                            /*exprLevel=*/true);
+                evalChildren(n.trueBranch, ctx);
+            }
             return;
         }
         case oscad::NodeKind::ModularIfElse: {
             auto& n = static_cast<const oscad::ModularIfElse&>(node);
-            if (truthy(evalExpr(*n.condition, ctx))) {
-                evalChildren(n.trueBranch, ctx);
-            } else {
-                evalChildren(n.falseBranch, ctx);
-            }
+            const auto& branch = truthy(evalExpr(*n.condition, ctx)) ? n.trueBranch : n.falseBranch;
+            checkDebug(branch.empty() ? node : *branch.front(), ctx, /*forced=*/false, /*exprLevel=*/true);
+            evalChildren(branch, ctx);
             return;
         }
         case oscad::NodeKind::ModularFor:
@@ -220,15 +240,20 @@ void Evaluator::evalChildren(const std::vector<const oscad::ASTNode*>& children,
             // always overwrites it before any subsequent read could see a
             // dangling value.
             lastCtx_ = &childCtx;
-            // Every real statement flows through this one call site
-            // (module/function bodies, for-loop bodies, if/else branches,
-            // let-block bodies, the top-level script) -- see
-            // debug_hooks.hpp's DebugHookFn doc comment for why this is
-            // the port's single statement-level debug checkpoint rather
-            // than the reference's many. Declarations are pure no-ops at
-            // statement-eval time (already hoisted into scope), so
-            // there's nothing useful to pause on.
-            if (child->kind() != oscad::NodeKind::ModuleDeclaration && child->kind() != oscad::NodeKind::FunctionDeclaration) {
+            // The port's statement-level debug checkpoint: every real
+            // statement flows through here (module/function bodies,
+            // for-loop bodies, if/else branches, let-block bodies, the
+            // top-level script). Declarations are pure no-ops at
+            // statement-eval time (already hoisted into scope), so there's
+            // nothing useful to pause on. ModularLet is excluded for a
+            // different reason: the reference's _eval_statement_impl
+            // explicitly skips it too (`t is not ModularLet` in its own
+            // guard) because evalLetBlock pauses on each of the let's
+            // ASSIGNMENTS instead -- checking here as well would produce
+            // one extra stop the reference never fires.
+            const oscad::NodeKind k = child->kind();
+            if (k != oscad::NodeKind::ModuleDeclaration && k != oscad::NodeKind::FunctionDeclaration &&
+                k != oscad::NodeKind::ModularLet) {
                 checkDebug(*child, childCtx);
             }
             evalStatement(*child, childCtx);