openscad-cpp-evaluator 1.15.0__tar.gz → 1.19.0__tar.gz

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.19.0}/CLAUDE.md

@@ -449,6 +449,39 @@ closed in one pass after a fresh "anything still unimplemented?" audit. Each bel
    all (`resolve_use_scopes`/`UseStatement` had zero hits in `openscad_evaluator`'s own `tests/`), so
    these were verified against real reference *behavior*, not ported from an existing test.
 
+   **File-level globals are evaluated ONCE per run (v1.16.0).** The main file's and every
+   `include`'s are, by the top-level statement pass, into the root `let_` level; a `use`d file's
+   are not -- `use` injects only declarations -- so `Evaluator::fileGlobal` evaluates ALL of that
+   file's top-level assignments, in source order, into a context of its own the first time anything
+   in the file reads one, and keeps it for the run. `ResolvedUseScopes::usedFileGlobals` carries
+   the per-file assignment lists and every entry point hands them over with
+   `Evaluator::setUsedFileGlobals` (CLI, both binding paths, the tests); a caller that skips that
+   keeps the old per-read fallback. Before this, `evalIdentifier`'s scope fallback re-evaluated the
+   assignment's expression on EVERY read from inside a function -- `callCtx()` isolates `let_` so the
+   root level was invisible -- which made `r = rands(0,1,1); function g() = r;` give `g() != g()`
+   (OpenSCAD: equal) and a 20K-element global list read 2000 times from a function cost 9.7s
+   (now 0.02s). Two deliberate divergences from OpenSCAD 2026.02.01, both verified against it:
+   a used file's globals are evaluated once, not once per call into the file (upstream's per-call
+   re-evaluation is a long-standing bug there, so its forward-read warning prints once here, not
+   per call); and a global read from a function BEFORE its assignment has run is `undef` with an
+   "Ignoring unknown variable" warning, exactly as upstream, where the old fallback had quietly
+   computed the not-yet-assigned value.
+**Scope-trail level table shrinks (v1.18.0).** `ScopeTrailStorage::parent_` and its indexed twin
+map level -> parent level in a vector indexed by level. Levels came from `++nextLevel_` and were
+never reused, so the vector grew 4 bytes per level for the whole run -- 3 x 64MB on a 13M-call
+script, plus the copy at every doubling -- and was 192MB of fractal_tree.scad's peak. A popped
+level is now marked -1 (0 still means "live, no parent": an isolated root), and when the NEWEST
+level dies `markDead` pops the vector back past every dead level above the newest live one, whose
+numbers `openLevel` then hands out again. Every invariant `lookup()`'s sorted-merge walk relies on
+holds: a reused number is greater than every level still holding an entry (all higher levels were
+dead and `popLevel` had already removed their entries), so a name's push-stack stays ascending,
+and a live level's number never changes -- an escaping closure that keeps a level alive simply
+stops the shrink at it (`tests/test_scope_trail.cpp` covers both). The ancestry walk now stops at
+`ancestor > 0` rather than `!= 0`. Same PR: `callCtxFor`'s per-call scan over active declarations
+does the integer span test before the origin STRING compare (`_platform_memcmp` was 1.4% of
+fractal_tree), and driveVm's completion branch no longer copies the finished frame's name. Anklet
+74 -> 63MB, a 4M-call synthetic 380 -> 258MB, fractal_tree -3.4% wall.
+
 **Known gap closed in Phase 3, worth remembering for Phase 5+**: every builtin resolve function must
 call `resolveCallArgs` (call_args.hpp), never bare `resolveArgs`, or a `$`-prefixed named call
 argument (`circle(r=2, $fn=64)`) silently fails to reach `ctx.dyn`. Caught by a geometric-correctness
@@ -910,6 +943,28 @@ grep for `ponytail:`.
   operation`. `linear_extrude`/`rotate_extrude`/`offset` are always-2D and `projection` always-3D, so
   they skip the "mixing" line and emit only the second; `roof()` emits neither, matching the
   reference. Background (`%`) children are exempt.
+  **The emptiness test is cached on the body (`ColoredBody::knownEmpty`, v1.17.0).** It used to
+  call `Manifold::NumTri()` on every child at every level, and every Manifold accessor goes through
+  `GetImpl()`, which materialises a lazy transform (a full mesh + collider copy) and runs a lazy
+  boolean -- so each leaf was copied once per ancestor transform, and because every node kept its
+  `bodies` until the tree died, all those copies stayed alive: fractal_tree.scad held 72,929
+  transformed copies of 1024 leaves (3.1GB). Now a body is asked once, the flag rides along on the
+  struct copies transform/colour/flatten make (emptiness is transform-invariant, and every generate
+  function that builds a new body starts from a fresh `ColoredBody`), and `generateTreeImpl` clears
+  each child's `bodies` once the parent has consumed them (move-assigning a fresh vector: `clear()`
+  and `= {}` both keep the capacity, and 35K nodes x 592-byte slots was 230MB) -- only top-level
+  bodies leave, a cache hit re-fills from the cache, and the bindings' `csg_tree` facade no longer
+  converts per-node bodies (it used to `GetMeshGL()` every node into numpy on every evaluate(), for
+  a dump that never read them). Three more forcing points had to go for the chain to stay lazy: the
+  booleans' `Status()` operand filter (now `bodyStatus()`, same cache), the boolean RESULT's own
+  emptiness (derived from the operands' flags -- a union is non-empty if any operand is -- rather
+  than asked), and `attachTriColors`, which `GetMeshGL()`'d every boolean result and now runs only
+  when the operands could actually disagree on colour. `Evaluator::generatedNodeCount` replaced
+  "does the child have bodies" as the cache-hit proxy in tests. Transforms compose lazily inside
+  Manifold and each leaf is transformed once, at the boolean that needs it. fractal_tree 3.1GB ->
+  0.67GB, Dalek 370 -> 277MB, snappy-reprap full_assembly 1.6GB -> 0.87GB; wall time neutral to
+  -3% interleaved. The output is geometrically identical (triangle count, area, volume) but not
+  byte-identical: Manifold evaluates one flat batch union instead of our old level-by-level order.
 
   Doing this centrally is also what keeps `generateCsg` safe: it builds ONE result and switches on
   whether it holds a `body` or a `section`, so a group that changed dimension part-way dereferenced
@@ -1425,6 +1480,39 @@ than the current pause point). Ported identically (same qualifier syntax, same e
 - `tools/cli/main.cpp` — a 3-line wrapper: builds `args` from `argv`, calls `runCli(args)` with the
   real `std::cin`/`std::cout`/`std::cerr`, returns its exit code.
 
+## Coverage
+
+`Evaluator(coverage=true)` records which parts of a run's source actually executed and
+fills `coverageResult`: `spans` (one per coverable node), `files` (one `CoverageFileSummary`
+per origin, sorted: statements/branches/bodies/spans, each with a hit count and a percent;
+`branches` counts Branch spans plus arm Statements, `percent` is over every span) and `total`
+(the same over every file). `summarizeCoverage()` is public so an aggregated span list can be
+re-summarised. Bindings: `Evaluator(coverage=True)` → `ev.coverage_result`, a dict
+`{spans, files, total}` of plain dicts. The vocabulary is fixed in one place,
+`coverage.hpp`/`coverage.cpp`, and used by both the recorder and the universe walk, so
+"covered" and "uncovered" never disagree about what counts:
+
+- **statement** — every node in a statement list (top level, module/if/for/let bodies,
+  `render()` children). A modifier (`%`/`#`/`!`/`*`) is the statement; the call it wraps is
+  not one of its own. The first statement of an if/else arm carries `arm=true`.
+- **branch** — a ternary arm, a comprehension if/else arm, the right operand of `&&`/`||`.
+- **body** — a function, module or function-literal declaration: was it ever entered?
+
+Hits are recorded at deliberate points, once per execution: `evalChildren`'s statement loop
+and `Op::Cover` (emitted per statement by `compileOneStatement`/`tryCompileAssignmentBlock`
+and at every arm, only when the Evaluator was built with coverage — chunks are per-Evaluator)
+on the two paths; `enterUserCall` for bodies; the arm sites in `evalExpr`, the tail
+trampoline (`simplifyTailStep`, which bypasses `evalExpr`'s own TernaryOp case) and the
+comprehension if/else cases. **Not** from `checkDebug`: the debugger checkpoints an if-arm's
+first statement twice and the `if` itself never, so piggybacking on it gave counts that
+differed between the VM and the interpreter. `Coverage.VmAndInterpreterAgree` compares the
+covered set under both and is the test that keeps them honest. The VM stays on under
+coverage (unlike a debug hook). The hit table is indexed by the node's `(treeId, slot)`
+numbering, so a hit is an array increment. Used-file globals are in the universe via
+`usedFileGlobals_`; everything else comes from the processed node list with each node's own
+`origin`, so includes and `use`d files report under their own paths. Let-bindings and plain
+comprehension elements are not in the vocabulary; hits on them are simply not reported.
+
 ## `render()` in expression position
 
 `render()` has two jobs, decided by where it is written:

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.19.0}/PKG-INFO

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

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.19.0}/bindings/module.cpp

@@ -26,6 +26,7 @@
 #include "openscad_cpp_evaluator/freetype_font_provider.hpp"
 #include "openscad_cpp_evaluator/mesh_check.hpp"
 #include "openscad_cpp_evaluator/manifold_cache.hpp"
+#include "openscad_cpp_evaluator/coverage.hpp"
 #include "openscad_cpp_evaluator/profile.hpp"
 #include "openscad_cpp_evaluator/value.hpp"
 
@@ -223,8 +224,9 @@ nb::dict idSpansToDict(const std::vector<IdSpan>& idSpans) {
     return d;
 }
 
-// CSGNode -> a facade `_CSGNode` (kind/params/bodies/is_builtin/children),
-// recursively, eagerly converting every field to plain Python data. No
+// CSGNode -> a facade `_CSGNode` (kind/params/is_builtin/children; `bodies`
+// is always empty, see below), recursively, eagerly converting every field
+// to plain Python data. No
 // lifetime extension needed -- CSGParams (Value-only, see csg_node.hpp) and
 // ColoredBody never hold AST pointers, so the result is fully self-contained
 // once built, unlike CSGNode::node itself (deliberately not exposed: the AST
@@ -234,15 +236,14 @@ nb::dict idSpansToDict(const std::vector<IdSpan>& idSpans) {
 nb::object csgNodeToPy(const oscadeval::CSGNode& node) {
     nb::dict params;
     for (const auto& [k, v] : node.params) params[nb::str(k.c_str())] = valueToPy(v);
+    // Deliberately no bodies. This used to GetMeshGL() every body of every
+    // node in the tree into numpy on every evaluate() -- and the only
+    // consumer, format_csg_tree(), never read them. Since v1.17.0 an inner
+    // node's bodies are released once its parent has consumed them (see
+    // generateTreeImpl), so there is nothing here to convert anyway; and a
+    // body the tree still holds may be a LAZY Manifold whose GetMeshGL()
+    // would materialise the very transform that release exists to avoid.
     nb::list bodies;
-    for (const oscadeval::ColoredBody& cb : node.bodies) {
-        if (!cb.isDisplayOnly() && (!cb.body || cb.body->IsEmpty())) continue;
-        // ColoredBody here is const in this walk (tree ownership stays with
-        // the caller) -- GetMeshGL() itself is logically read-only, so a
-        // const_cast here is safe/local, mirroring bodyToDict's mutating
-        // signature only because manifold3d's own API isn't const-qualified.
-        bodies.append(bodyToDict(const_cast<oscadeval::ColoredBody&>(cb)));
-    }
     nb::list children;
     for (const std::unique_ptr<oscadeval::CSGNode>& child : node.children) children.append(csgNodeToPy(*child));
     return facadeAttr("_CSGNode")(node.kind, params, bodies, node.isBuiltin, children);
@@ -432,9 +433,51 @@ nb::list exportModelPy(const std::string& path, const Geometry& geom, const std:
     return out;
 }
 
+nb::dict coverageSummaryToPy(const oscadeval::CoverageFileSummary& f) {
+    nb::dict d;
+    d["origin"] = f.origin;
+    d["statements"] = f.statements;
+    d["statements_hit"] = f.statements_hit;
+    d["branches"] = f.branches;
+    d["branches_hit"] = f.branches_hit;
+    d["bodies"] = f.bodies;
+    d["bodies_hit"] = f.bodies_hit;
+    d["spans"] = f.spans;
+    d["spans_hit"] = f.spans_hit;
+    d["percent"] = f.percent();
+    d["statement_percent"] = f.statement_percent();
+    d["branch_percent"] = f.branch_percent();
+    d["body_percent"] = f.body_percent();
+    return d;
+}
+
+nb::object coverageResultToPy(const std::optional<oscadeval::CoverageResult>& cr) {
+    if (!cr) return nb::none();
+    nb::list files;
+    for (const oscadeval::CoverageFileSummary& f : cr->files) files.append(coverageSummaryToPy(f));
+    nb::list out;
+    for (const oscadeval::CoverageSpan& s : cr->spans) {
+        nb::dict d;
+        d["origin"] = s.origin;
+        d["line"] = s.line;
+        d["column"] = s.column;
+        d["start"] = s.start_offset;
+        d["end"] = s.end_offset;
+        d["kind"] = oscadeval::coverageKindName(s.kind);
+        d["arm"] = s.arm;
+        d["hits"] = s.hits;
+        out.append(d);
+    }
+    nb::dict result;
+    result["spans"] = out;
+    result["files"] = files;
+    result["total"] = coverageSummaryToPy(cr->total);
+    return result;
+}
+
 nb::object evaluate(const std::string& path, nb::dict viewportParams,
                      std::shared_ptr<oscadeval::ManifoldCache> manifoldCache, bool profile,
-                     bool generate, bool strictCommas) {
+                     bool generate, bool strictCommas, bool coverage) {
     std::unordered_map<std::string, oscadeval::Value> vp = toViewportParams(viewportParams);
 
     std::vector<oscadeval::ColoredBody> bodies;
@@ -442,6 +485,7 @@ nb::object evaluate(const std::string& path, nb::dict viewportParams,
     std::vector<IdSpan> idSpans;
     std::vector<std::unique_ptr<oscadeval::CSGNode>> csgTree;
     std::optional<oscadeval::ProfileResult> profileResult;
+    std::optional<oscadeval::CoverageResult> coverageResult;
     nb::dict dyn;
     nb::object dynExplicit;
     {
@@ -456,7 +500,8 @@ nb::object evaluate(const std::string& path, nb::dict viewportParams,
             if (strictCommas) strict.emplace();
             oscad::ParsedProgram program = oscad::getProgramFromFile(path);
             oscadeval::ResolvedUseScopes used = oscadeval::resolveUseScopes(program.nodes, path, logFn);
-            oscadeval::Evaluator ev(logFn, nullptr, manifoldCache, oscadeval::DebugHooks{}, profile);
+            oscadeval::Evaluator ev(logFn, nullptr, manifoldCache, oscadeval::DebugHooks{}, profile, coverage);
+            ev.setUsedFileGlobals(used.usedFileGlobals);
             oscadeval::EvalContext ctx = oscadeval::EvalContext::makeRoot(used.rootScope.get());
             bodies = oscadeval::toRenderableBodies(ev.evaluate(used.processedNodes, ctx, vp, generate));
             collectIdSpans(ev, idSpans);
@@ -465,6 +510,7 @@ nb::object evaluate(const std::string& path, nb::dict viewportParams,
             // which a resolve-only caller has no use for.
             if (generate) csgTree = std::move(ev.csgTree);
             profileResult = std::move(ev.profileResult);
+            coverageResult = std::move(ev.coverageResult);
             {
                 nb::gil_scoped_acquire g; // building Python objects needs the GIL back
                 std::tie(dyn, dynExplicit) = dynStateToPy(ctx);
@@ -494,7 +540,7 @@ nb::object evaluate(const std::string& path, nb::dict viewportParams,
     auto geom = std::make_shared<Geometry>();
     geom->bodies = std::move(bodies);
     return nb::make_tuple(bodiesToList(geom->bodies), echoList, idSpansToDict(idSpans), csgTreeToPy(csgTree),
-                           profileResultToPy(profileResult), dyn, dynExplicit, geom);
+                           profileResultToPy(profileResult), dyn, dynExplicit, geom, coverageResultToPy(coverageResult));
 }
 
 // ------------------------------------------------------------------------
@@ -764,6 +810,7 @@ nb::object debugEvaluate(const std::string& path, nb::dict viewportParams, nb::c
             oscadeval::Evaluator ev(echoCpp, nullptr, manifoldCache, hooks, false);
             evPtr = &ev;
             if (fastContinueSignal) ev.setFastContinueInterruptFlag(fastContinueSignal->flag());
+            ev.setUsedFileGlobals(used.usedFileGlobals);
             oscadeval::EvalContext ctx = oscadeval::EvalContext::makeRoot(used.rootScope.get());
             bodies = oscadeval::toRenderableBodies(ev.evaluate(used.processedNodes, ctx, vp));
             collectIdSpans(ev, idSpans);
@@ -908,7 +955,14 @@ NB_MODULE(_openscad_cpp_evaluator, m) {
 
     m.def("evaluate", &evaluate, nb::arg("path"), nb::arg("viewport_params"), nb::arg("manifold_cache") = nullptr,
           nb::arg("profile") = false, nb::arg("generate") = true, nb::arg("strict_commas") = false,
-          "Evaluate a .scad file; return (bodies, echoes, id_to_node, csg_tree, profile_result, dyn, dyn_explicit).\n"
+          nb::arg("coverage") = false,
+          "Evaluate a .scad file; return (bodies, echoes, id_to_node, csg_tree, profile_result, dyn, dyn_explicit, "
+          "geometry, coverage_result).\n"
+          "coverage=True records which statements, branch arms and bodies ran: coverage_result is a dict "
+          "{spans, files, total}: spans is a list of dicts (origin, line, column, start, end, kind, arm, hits), "
+          "one per coverable node of every file the run touched; files is one summary per origin, sorted "
+          "(statements/statements_hit, branches/branches_hit, bodies/bodies_hit, spans/spans_hit and the four "
+          "percent fields); total is the same over every file. None when off.\n"
           "generate=False stops after the resolve pass: the script runs and reports everything "
           "it normally would, but no Manifold geometry is built, and neither bodies nor csg_tree "
           "are populated.\n\n"

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.19.0}/include/openscad_cpp_evaluator/bytecode.hpp

@@ -728,6 +728,12 @@ enum class Op {
     // on failure, otherwise runs any chained node.children natively (rare;
     // not worth its own compiled path -- see AssertSite's own doc comment).
     AssertStatement,
+    // a = nativeStatements index of the AST node whose arm this is. Emitted
+    // only when the Evaluator was built with coverage on (compile-time
+    // flag, and chunks are per-Evaluator): Evaluator::coverHit(node), nothing
+    // else. Marks the arms the debugger never checkpoints in compiled code
+    // -- ternary arms, comprehension if/else arms, `&&`/`||` right operands.
+    Cover,
 };
 
 struct Instruction {

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.19.0}/include/openscad_cpp_evaluator/bytecode_compiler.hpp

@@ -21,7 +21,7 @@ namespace oscadeval {
 // whole function, unconditionally correct since nothing about this
 // function's behavior changes based on whether it happened to compile.
 std::optional<CompiledChunk> tryCompileFunction(const oscad::FunctionDeclaration& decl,
-                                                 const oscad::ScopeTable* scopeTable);
+                                                 const oscad::ScopeTable* scopeTable, bool coverage = false);
 
 // Compiles a bare STATEMENT-context expression -- an assignment's RHS, an
 // if/for condition, a module-call or echo()/assert() argument -- rather
@@ -50,7 +50,7 @@ std::optional<CompiledChunk> tryCompileFunction(const oscad::FunctionDeclaration
 // any callee inside it statically, the same way a function body's call
 // sites are.
 std::optional<CompiledChunk> tryCompileStatementExpr(const oscad::Expression& expr, const oscad::Scope* scope,
-                                                      const oscad::ScopeTable* scopeTable);
+                                                      const oscad::ScopeTable* scopeTable, bool coverage = false);
 
 // Compiles a run of SIBLING assignment statements sharing one scope --
 // exactly Evaluator::evalChildren's own `assignments` sub-list (stmt_eval.
@@ -85,7 +85,7 @@ std::optional<CompiledChunk> tryCompileStatementExpr(const oscad::Expression& ex
 //   instead of just for that one assignment's own RHS.
 std::optional<CompiledChunk> tryCompileAssignmentBlock(const std::vector<const oscad::Assignment*>& assigns,
                                                         const oscad::ScopeTable* scopeTable,
-                                                        const oscad::Scope* scope);
+                                                        const oscad::Scope* scope, bool coverage = false);
 
 // Attempts to compile `decl`'s parameter defaults + STATEMENT-list body
 // (decl.children) to bytecode (Stage 2) -- the module-side analog of
@@ -101,7 +101,7 @@ std::optional<CompiledChunk> tryCompileAssignmentBlock(const std::vector<const o
 // EXPRESSION (inside an if-condition/for-range/argument) can still bail
 // (via tryCompileStatementExpr's own NotCompilable, propagated up).
 std::optional<CompiledChunk> tryCompileModuleBody(const oscad::ModuleDeclaration& decl,
-                                                   const oscad::ScopeTable* scopeTable);
+                                                   const oscad::ScopeTable* scopeTable, bool coverage = false);
 
 // Same compilation (assignment/if/for/resolved-module-call get real
 // bytecode, everything else a native passthrough), but for an ARBITRARY
@@ -126,6 +126,6 @@ std::optional<CompiledChunk> tryCompileModuleBody(const oscad::ModuleDeclaration
 // scope()`, mirroring tryRunCompiledAssignmentBlock's own convention.
 std::optional<CompiledChunk> tryCompileChildrenList(const std::vector<const oscad::ASTNode*>& children,
                                                      const oscad::ScopeTable* scopeTable,
-                                                     const oscad::Scope* scope);
+                                                     const oscad::Scope* scope, bool coverage = false);
 
 } // namespace oscadeval

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.19.0}/include/openscad_cpp_evaluator/colored_body.hpp

@@ -53,6 +53,22 @@ struct ColoredBody {
     BodyRole role = BodyRole::Normal;
     std::optional<std::vector<std::array<float, 4>>> triColors; // per-triangle RGBA, multi-color CSG merges only
 
+    // Whether `body` is empty, once anything has asked (isEmptyBody,
+    // csg_generate.cpp). Asking Manifold is not free: every accessor goes
+    // through GetImpl(), which MATERIALIZES a lazy transform (a full copy of
+    // the mesh and its collider) and, for a boolean, runs it. Emptiness is
+    // invariant under transforms and colour, and every generate function
+    // that produces a genuinely new body starts from a fresh ColoredBody,
+    // so a copy carrying this flag is always still right. Before this, the
+    // dimension check at every tree level materialised every child at
+    // every level: fractal_tree.scad held 72,929 transformed copies of its
+    // 1024 leaf meshes at once (3.1GB).
+    std::optional<bool> knownEmpty;
+    // Same idea for Manifold::Status(), which the booleans consult to keep an
+    // invalid operand from poisoning a union: validity is transform-invariant
+    // too, and a boolean of valid operands is valid.
+    std::optional<manifold::Manifold::Error> knownStatus;
+
     // Set ONLY when a mesh could not be built into a valid Manifold -- in
     // practice a polyhedron() whose faces don't close the surface (it has
     // boundary edges), which Manifold reports by returning an *empty* body
@@ -75,6 +91,33 @@ struct ColoredBody {
     bool isDisplayOnly() const { return rawMesh.has_value(); }
 };
 
+// The cached questions -- see ColoredBody::knownEmpty. Ask Manifold once per
+// body, never once per tree level.
+inline bool bodyIsEmpty(ColoredBody& b) {
+    if (!b.knownEmpty) b.knownEmpty = !b.body || b.body->IsEmpty();
+    return *b.knownEmpty;
+}
+inline manifold::Manifold::Error bodyStatus(ColoredBody& b) {
+    if (!b.knownStatus) b.knownStatus = b.body ? b.body->Status() : manifold::Manifold::Error::NoError;
+    return *b.knownStatus;
+}
+
+// Emptiness of a union, from its operands' own flags and nothing else:
+// non-empty if any operand is known non-empty, empty if every one is known
+// empty, otherwise unknown (asked of Manifold later, if anyone ever asks).
+// `get` maps a range element to its ColoredBody.
+template <typename Range, typename Get>
+std::optional<bool> unionEmptyOf(const Range& ops, Get get) {
+    bool allKnownEmpty = true;
+    for (const auto& o : ops) {
+        const ColoredBody& b = get(o);
+        if (b.knownEmpty && !*b.knownEmpty) return false;
+        if (!b.knownEmpty) allKnownEmpty = false;
+    }
+    if (allKnownEmpty) return true;
+    return std::nullopt;
+}
+
 // `EvalContext::color`/CSGParams round-trip: a resolve function reads
 // ctx.color (double-precision, matching Value's own numeric type) but a
 // generate function only sees CSGParams (Value-typed, no ctx access) -- so

openscad_cpp_evaluator-1.19.0/include/openscad_cpp_evaluator/coverage.hpp

@@ -0,0 +1,116 @@
+#pragma once
+
+// Coverage: which parts of a script (and of the libraries it pulls in) ran.
+//
+// The unit of coverage is the checkpoint set the debugger already uses --
+// Evaluator::checkDebug fires for every statement, every function/module
+// body entered, every if/else arm's first statement, every ternary arm and
+// list-comprehension if/else arm -- plus two arms the debugger never needed
+// to stop at, the right operands of `&&`/`||`. Recording a hit is an array
+// increment indexed by the node's (treeId, slot), the dense per-parse
+// numbering ScopeTable relies on, so the bytecode VM stays on and a hit
+// costs no hashing and no string.
+//
+// What COULD have run -- the universe the report counts against -- comes
+// from a walk over the same trees (collectCoverable) using one predicate
+// for both sides, so "covered" and "uncovered" are one vocabulary. A hit
+// on a node outside that vocabulary (a let-binding, a plain comprehension
+// element) is simply not reported.
+
+#include "openscad_cpp_parser/ast/ast_node.hpp"
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace oscadeval {
+
+enum class CoverageKind {
+    Statement, // a statement in a module body, an if/for/let body, or at top level
+    Branch,    // a ternary arm, a comprehension if/else arm, a `&&`/`||` right operand
+    Body,      // a function, module or function-literal body: was it ever entered?
+};
+
+const char* coverageKindName(CoverageKind kind);
+
+struct CoverageSpan {
+    std::string origin;
+    int line = 0;
+    int column = 0;
+    int start_offset = 0;
+    int end_offset = 0;
+    CoverageKind kind = CoverageKind::Statement;
+    // A Statement that is the first of an if/else arm. Branch coverage counts
+    // these alongside the Branch kind; they stay Statements so a statement
+    // count is still a statement count.
+    bool arm = false;
+    std::uint32_t hits = 0;
+};
+
+// Per-file totals. "branches" counts Branch spans plus arm Statements (an
+// if/else arm is a branch too); those arm statements are ALSO in
+// "statements", since a statement count should be a statement count.
+// "percent" is over every span in the file, whatever its kind.
+struct CoverageFileSummary {
+    std::string origin;
+    std::uint32_t statements = 0, statements_hit = 0;
+    std::uint32_t branches = 0, branches_hit = 0;
+    std::uint32_t bodies = 0, bodies_hit = 0;
+    std::uint32_t spans = 0, spans_hit = 0;
+    double percent() const { return spans ? 100.0 * spans_hit / spans : 100.0; }
+    double statement_percent() const { return statements ? 100.0 * statements_hit / statements : 100.0; }
+    double branch_percent() const { return branches ? 100.0 * branches_hit / branches : 100.0; }
+    double body_percent() const { return bodies ? 100.0 * bodies_hit / bodies : 100.0; }
+};
+
+struct CoverageResult {
+    std::vector<CoverageSpan> spans;         // one per coverable node, source order per tree
+    std::vector<CoverageFileSummary> files;  // one per origin, sorted by origin
+    CoverageFileSummary total;               // every file together (origin empty)
+};
+
+// The per-file and total summaries for `spans`; buildCoverageResult calls
+// this, and a merged/aggregated span list (BelfrySCAD's --test --coverage)
+// can call it again.
+void summarizeCoverage(CoverageResult& result);
+
+class CoverageRecorder {
+public:
+    void clear() { hits_.clear(); }
+    void hit(const oscad::ASTNode& node) {
+        const std::uint32_t tree = node.treeId(), slot = node.slot();
+        if (tree >= hits_.size()) hits_.resize(tree + 1);
+        std::vector<std::uint32_t>& slots = hits_[tree];
+        if (slot >= slots.size()) slots.resize(slot + 1, 0);
+        ++slots[slot];
+    }
+    std::uint32_t hitsFor(const oscad::ASTNode& node) const {
+        const std::uint32_t tree = node.treeId(), slot = node.slot();
+        if (tree >= hits_.size()) return 0;
+        const std::vector<std::uint32_t>& slots = hits_[tree];
+        return slot < slots.size() ? slots[slot] : 0;
+    }
+
+private:
+    std::vector<std::vector<std::uint32_t>> hits_;
+};
+
+struct Coverable {
+    const oscad::ASTNode* node = nullptr;
+    CoverageKind kind = CoverageKind::Statement;
+    bool arm = false;
+};
+
+// Every coverable node under `roots` (a top-level statement list: the main
+// file with its includes spliced in and any use-injected declarations) plus
+// `extraStatements` (a used file's own top-level assignments, which `use`
+// never splices anywhere -- see Evaluator::setUsedFileGlobals). Source
+// order within each tree; a node reachable twice is listed once.
+std::vector<Coverable> collectCoverable(const std::vector<const oscad::ASTNode*>& roots,
+                                        const std::vector<const oscad::ASTNode*>& extraStatements);
+
+CoverageResult buildCoverageResult(const std::vector<const oscad::ASTNode*>& roots,
+                                   const std::vector<const oscad::ASTNode*>& extraStatements,
+                                   const CoverageRecorder& recorder);
+
+} // namespace oscadeval

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.19.0}/include/openscad_cpp_evaluator/eval_use.hpp

@@ -15,9 +15,21 @@ namespace oscadeval {
 // must keep this struct alive for as long as evaluation runs against
 // .rootScope/.processedNodes, since declarations injected from a used file
 // are raw (non-owning) pointers into it.
+// One used file's own top-level assignments, in source order, keyed by
+// that file's root Scope (the one its injected declarations were
+// re-anchored onto). Evaluator::setUsedFileGlobals takes the list so a
+// used file's globals can be evaluated ONCE per run, eagerly, the first
+// time anything in that file reads one -- see Evaluator::fileGlobal.
+// Raw pointers into usedFileAsts, same lifetime contract as processedNodes.
+struct UsedFileGlobals {
+    const oscad::Scope* root = nullptr;
+    std::vector<const oscad::ASTNode*> assignments;
+};
+
 struct ResolvedUseScopes {
     std::vector<std::vector<std::unique_ptr<oscad::ASTNode>>> usedFileAsts;
     std::vector<std::unique_ptr<oscad::Scope>> usedFileScopes;
+    std::vector<UsedFileGlobals> usedFileGlobals;
     // What currentFile should actually be evaluated as: declarations
     // injected via `use` (raw pointers into usedFileAsts, above), followed
     // by currentFile's own nodes (raw pointers into the caller-owned

{openscad_cpp_evaluator-1.15.0 → openscad_cpp_evaluator-1.19.0}/include/openscad_cpp_evaluator/evaluator.hpp

@@ -7,6 +7,8 @@
 #include "openscad_cpp_evaluator/csg_node.hpp"
 #include "openscad_cpp_evaluator/debug_hooks.hpp"
 #include "openscad_cpp_evaluator/eval_context.hpp"
+#include "openscad_cpp_evaluator/eval_use.hpp"
+#include "openscad_cpp_evaluator/coverage.hpp"
 #include "openscad_cpp_evaluator/eval_error.hpp"
 #include "openscad_cpp_evaluator/font_provider.hpp"
 #include "openscad_cpp_evaluator/manifold_cache.hpp"
@@ -83,7 +85,7 @@ public:
     // work at all.
     explicit Evaluator(EchoFn echoFn = {}, std::shared_ptr<FontProvider> fontProvider = nullptr,
                         std::shared_ptr<ManifoldCache> manifoldCache = nullptr, DebugHooks debugHooks = {},
-                        bool profiling = false);
+                        bool profiling = false, bool coverage = false);
 
     // Text/font builtins' shared access to the resolved FontProvider
     // (lazily constructing the built-in default on first call if none was
@@ -285,6 +287,11 @@ public:
                           const oscad::ASTNode* producer);
 
     std::unordered_map<uint32_t, const oscad::ASTNode*> idToNode;
+    // Nodes whose bodies were actually generated this run (not served from
+    // the ManifoldCache). Reset per run; a diagnostic, and the only honest
+    // way for a test to tell a cache hit from a miss now that an inner
+    // node's bodies are released the moment its parent has consumed them.
+    std::size_t generatedNodeCount = 0;
     std::unordered_map<uint32_t, std::optional<std::array<float, 4>>> idToColor;
 
     // Called by primitive-construction generate functions (cube, sphere,
@@ -653,6 +660,22 @@ public:
     // resolve+generate bracket evaluate() itself runs). Mirrors the
     // reference's Evaluator.profile_result.
     std::optional<ProfileResult> profileResult;
+    // Filled by evaluate() when constructed with coverage=true: one span per
+    // coverable node of every tree the run touched, with its hit count.
+    // See coverage.hpp for the vocabulary.
+    std::optional<CoverageResult> coverageResult;
+
+    bool coverageEnabled() const { return coverage_; }
+    // Called once per statement execution (evalChildren on the interpreter
+    // side, Op::Cover on the compiled side), once per body entry
+    // (enterUserCall), and once per branch arm taken (ternary, comprehension
+    // if/else, `&&`/`||` right operand). Deliberately NOT from checkDebug:
+    // the debugger's checkpoints double up on an if-arm's first statement
+    // and never land on the `if` itself. Free when coverage is off: one
+    // predictable branch.
+    void coverHit(const oscad::ASTNode& node) {
+        if (coverage_) coverageRecorder_.hit(node);
+    }
 
     // The resolved (and, after evaluate() runs, generated) CSG tree from the
     // most recent evaluate() call -- moved here from evaluateImpl's local
@@ -1396,6 +1419,11 @@ public:
     // the same decision evalUserFunction*/evalFunctionLiteral* already
     // make before calling lookupOrCompileChunk/lookupCompiledLiteralChunk
     // themselves.
+    // Every used file's own top-level assignments (ResolvedUseScopes::
+    // usedFileGlobals), so fileGlobal() can evaluate a file's globals once.
+    // A caller that skips this keeps the old per-read fallback for used files.
+    void setUsedFileGlobals(std::vector<UsedFileGlobals> globals) { usedFileGlobals_ = std::move(globals); }
+
     bool useBytecodeVm() const {
         return bytecodeVmEnabled() && (!debugHooks_.debugHook || fastContinueBreakpoints_.has_value());
     }
@@ -1941,6 +1969,25 @@ private:
     // lifetime contract as every other raw AST/EvalContext pointer this
     // class holds).
     const EvalContext* rootCtx_ = nullptr;
+
+    // File-level globals are evaluated ONCE per run. The main file's (and
+    // every include's) already are, by the top-level statement pass, into
+    // rootCtx_'s own let_ level. A used file's are not -- `use` injects only
+    // its declarations -- so the first read of any global from that file
+    // evaluates ALL of its assignments, in source order, into a context of
+    // its own, kept here for the rest of the run. Before this, a function
+    // reading a global re-evaluated the assignment's expression on every
+    // read (evalIdentifier's scope fallback): `r = rands(0,1,1); function
+    // g() = r;` gave `g() != g()`, and a 20K-element global list read 2000
+    // times from a function cost 9.7s. OpenSCAD itself re-evaluates a used
+    // file's globals per CALL, which is a long-standing upstream bug, not
+    // behaviour to match. Returns nullopt for a file this evaluator was
+    // never told about (setUsedFileGlobals), so such a caller keeps the
+    // old fallback; nullptr for a known file whose global is not (yet)
+    // assigned -- a forward read, undef in OpenSCAD too.
+    std::optional<const Value*> fileGlobal(const oscad::Scope& fileRoot, const std::string& name);
+    std::vector<UsedFileGlobals> usedFileGlobals_;
+    std::unordered_map<const oscad::Scope*, EvalContext> usedFileCtx_;
     // The most recent ctx seen by evalStatement() -- error()'s only way to
     // reach a locals snapshot for its own errorBreak hook call, since
     // error() itself (called from dozens of builtin resolve functions)
@@ -1954,6 +2001,8 @@ private:
     // -- Profiling (Phase 9) ----------------------------------------------
 
     bool profiling_ = false;
+    bool coverage_ = false;
+    CoverageRecorder coverageRecorder_;
     std::map<ProfileSiteKey, CallSiteProfile> profileSites_;
     std::set<ProfileSiteKey> profileActive_; // site keys with a call currently on callStack_
     std::vector<double> profileChildTime_;   // parallel aux stack to callStack_