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

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

@@ -1480,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.18.0 → openscad_cpp_evaluator-1.19.0}/PKG-INFO

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

{openscad_cpp_evaluator-1.18.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"
 
@@ -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,7 @@ 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));
@@ -466,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);
@@ -495,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));
 }
 
 // ------------------------------------------------------------------------
@@ -910,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.18.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.18.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.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.18.0 → openscad_cpp_evaluator-1.19.0}/include/openscad_cpp_evaluator/evaluator.hpp

@@ -8,6 +8,7 @@
 #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"
@@ -84,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
@@ -659,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
@@ -1984,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_

{openscad_cpp_evaluator-1.18.0 → openscad_cpp_evaluator-1.19.0}/pyproject.toml

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

{openscad_cpp_evaluator-1.18.0 → openscad_cpp_evaluator-1.19.0}/python/openscad_cpp_evaluator/__init__.py

@@ -532,7 +532,7 @@ class Evaluator:
     """
 
     def __init__(self, echo_fn=None, debug_hook=None, error_break_fn=None, return_hook=None,
-                 manifold_cache=None, profile=False, fast_continue_signal=None):
+                 manifold_cache=None, profile=False, fast_continue_signal=None, coverage=False):
         self._echo_fn = echo_fn
         self._debug_hook = debug_hook
         self._error_break_fn = error_break_fn
@@ -540,8 +540,17 @@ class Evaluator:
         self._manifold_cache = manifold_cache
         self._profile = profile
         self._fast_continue_signal = fast_continue_signal
+        self._coverage = coverage
         self.csg_tree = []
         self.profile_result = None
+        # coverage=True: after evaluate(), {"spans": [...], "files": [...],
+        # "total": {...}}. spans: one dict (origin, line, column, start, end,
+        # kind, arm, hits) per coverable node -- statement, branch arm, or
+        # function/module body -- of every file the run touched. files: one
+        # summary per origin, sorted, with counts and percentages per kind
+        # and overall; total: the same over every file. None when off. See
+        # coverage.hpp.
+        self.coverage_result = None
         self.dyn = {}
         self.dyn_explicit = set()
 
@@ -583,9 +592,9 @@ class Evaluator:
                 self.geometry = None
             else:
                 (body_dicts, echoes, id_spans, csg_tree, profile_result, dyn,
-                 dyn_explicit, geometry) = _ext.evaluate(
+                 dyn_explicit, geometry, coverage_result) = _ext.evaluate(
                     source_path, vp, self._manifold_cache, self._profile, generate,
-                    strict_commas)
+                    strict_commas, self._coverage)
                 # The evaluated bodies, still on the C++ side. Stashed like
                 # csg_tree/profile_result rather than returned, so
                 # evaluate()'s own 2-tuple result is unchanged -- callers
@@ -598,6 +607,7 @@ class Evaluator:
                         self._echo_fn(line)
                 self.csg_tree = csg_tree
                 self.profile_result = profile_result
+                self.coverage_result = coverage_result
             self.dyn = dyn
             self.dyn_explicit = dyn_explicit
         except EvalError:

{openscad_cpp_evaluator-1.18.0 → openscad_cpp_evaluator-1.19.0}/src/CMakeLists.txt

@@ -12,6 +12,7 @@ add_library(openscad_cpp_evaluator STATIC
   colored_body.cpp
   css_colors.cpp
   csg_resolve.cpp
+  coverage.cpp
   csg_generate.cpp
   measure_geometry.cpp
   manifold_cache.cpp

{openscad_cpp_evaluator-1.18.0 → openscad_cpp_evaluator-1.19.0}/src/bytecode_compiler.cpp

@@ -271,7 +271,7 @@ class Compiler;
 bool compileFunctionLike(CompiledChunk& chunk, const oscad::Scope* staticScope, const oscad::ASTNode* selfDecl,
                           const oscad::ScopeTable* scopeTable, std::vector<EnclosingLevel> enclosing,
                           const std::vector<std::unique_ptr<oscad::ParameterDeclaration>>& params,
-                          const oscad::Expression& bodyExpr);
+                          const oscad::Expression& bodyExpr, bool coverage = false);
 
 class Compiler {
 public:
@@ -291,9 +291,9 @@ public:
     // when compiling a FunctionLiteral nested inside another compile --
     // see the FunctionLiteral case in compileExpr).
     Compiler(CompiledChunk& chunk, const oscad::Scope* scope, const oscad::ASTNode* selfDecl,
-              const oscad::ScopeTable* scopeTable, std::vector<EnclosingLevel> enclosing)
+              const oscad::ScopeTable* scopeTable, std::vector<EnclosingLevel> enclosing, bool coverage = false)
         : chunk_(chunk), scope_(scope), selfDecl_(selfDecl), scopeTable_(scopeTable),
-          enclosing_(std::move(enclosing)) {}
+          enclosing_(std::move(enclosing)), coverage_(coverage) {}
 
     // A node's own lexical scope, or null. Replaces ASTNode::scope(),
     // which is gone: one parsed tree is shared between evaluations, so a
@@ -470,7 +470,7 @@ public:
                 childEnclosing.push_back({selfDecl_, &scope});
                 CompiledChunk literalChunk;
                 if (!compileFunctionLike(literalChunk, scopeOf(n), &n, scopeTable_, std::move(childEnclosing), n.parameters,
-                                          *n.body)) {
+                                          *n.body, coverage_)) {
                     throw NotCompilable{};
                 }
                 // Effective capture set: `n`'s own direct free-variable
@@ -555,10 +555,12 @@ public:
                 compileExpr(*n.condition, out, scope); // condition is never tail
                 size_t jumpToFalse = out.size();
                 out.push_back({Op::JumpIfFalse, 0, 0, nullptr});
+                cover(out, n.trueExpr.get());
                 compileExpr(*n.trueExpr, out, scope, tail); // both branches inherit
                 size_t jumpToEnd = out.size();
                 out.push_back({Op::Jump, 0, 0, nullptr});
                 out[jumpToFalse].a = static_cast<int>(out.size());
+                cover(out, n.falseExpr.get());
                 compileExpr(*n.falseExpr, out, scope, tail);
                 out[jumpToEnd].a = static_cast<int>(out.size());
                 return;
@@ -568,6 +570,7 @@ public:
                 compileExpr(*n.left, out, scope);
                 size_t j1 = out.size();
                 out.push_back({Op::JumpIfFalse, 0, 0, nullptr});
+                cover(out, n.right.get());
                 compileExpr(*n.right, out, scope);
                 size_t j2 = out.size();
                 out.push_back({Op::JumpIfFalse, 0, 0, nullptr});
@@ -586,6 +589,7 @@ public:
                 compileExpr(*n.left, out, scope);
                 size_t j1 = out.size();
                 out.push_back({Op::JumpIfTrue, 0, 0, nullptr});
+                cover(out, n.right.get());
                 compileExpr(*n.right, out, scope);
                 size_t j2 = out.size();
                 out.push_back({Op::JumpIfTrue, 0, 0, nullptr});
@@ -1172,6 +1176,7 @@ public:
                 compileExpr(*n.condition, out, scope);
                 size_t j = out.size();
                 out.push_back({Op::JumpIfFalse, 0, 0, nullptr});
+                cover(out, n.trueExpr.get());
                 compileListCompBody(*n.trueExpr, out, scope);
                 out[j].a = static_cast<int>(out.size());
                 return;
@@ -1181,10 +1186,12 @@ public:
                 compileExpr(*n.condition, out, scope);
                 size_t j = out.size();
                 out.push_back({Op::JumpIfFalse, 0, 0, nullptr});
+                cover(out, n.trueExpr.get());
                 compileListCompBody(*n.trueExpr, out, scope);
                 size_t jend = out.size();
                 out.push_back({Op::Jump, 0, 0, nullptr});
                 out[j].a = static_cast<int>(out.size());
+                cover(out, n.falseExpr.get());
                 compileListCompBody(*n.falseExpr, out, scope);
                 out[jend].a = static_cast<int>(out.size());
                 return;
@@ -1511,6 +1518,11 @@ public:
     void compileOneStatement(const oscad::ASTNode& stmt, std::vector<Instruction>& out) {
         using oscad::NodeKind;
         trackSpan(stmt);
+        // One coverage hit per statement execution, whichever way it is
+        // compiled below (inline or Op::NativeStatement -- the native path
+        // calls evalStatement directly, not evalChildren, so it does not
+        // count itself). Mirrors evalChildren's own coverHit.
+        if (stmt.kind() != NodeKind::ModuleDeclaration && stmt.kind() != NodeKind::FunctionDeclaration) cover(out, &stmt);
         // A statement's own .scope() can differ from this whole chunk's
         // fixed scope_ member (e.g. a `use` statement earlier in the SAME
         // script/module body changes what later statements can see) --
@@ -1916,14 +1928,20 @@ private:
     std::vector<EnclosingLevel> enclosing_;
     int nextSlot_ = 0;
     int nextIterList_ = 0;
+    bool coverage_ = false; // emit Op::Cover for every statement and every arm
+
+public:
+    void cover(std::vector<Instruction>& out, const oscad::ASTNode* arm) {
+        if (coverage_) out.push_back({Op::Cover, internNativeStatement(arm), 0, nullptr});
+    }
 };
 
 bool compileFunctionLike(CompiledChunk& chunk, const oscad::Scope* staticScope, const oscad::ASTNode* selfDecl,
                           const oscad::ScopeTable* scopeTable, std::vector<EnclosingLevel> enclosing,
                           const std::vector<std::unique_ptr<oscad::ParameterDeclaration>>& params,
-                          const oscad::Expression& bodyExpr) {
+                          const oscad::Expression& bodyExpr, bool coverage) {
     chunk.selfDecl = selfDecl;
-    Compiler compiler(chunk, staticScope, selfDecl, scopeTable, std::move(enclosing));
+    Compiler compiler(chunk, staticScope, selfDecl, scopeTable, std::move(enclosing), coverage);
     CompileScope bodyScope;
     bodyScope.push();
     for (const auto& p : params) {
@@ -1960,19 +1978,19 @@ bool compileFunctionLike(CompiledChunk& chunk, const oscad::Scope* staticScope,
 } // namespace
 
 std::optional<CompiledChunk> tryCompileFunction(const oscad::FunctionDeclaration& decl,
-                                                 const oscad::ScopeTable* scopeTable) {
+                                                 const oscad::ScopeTable* scopeTable, bool coverage) {
     CompiledChunk chunk;
     if (!compileFunctionLike(chunk, scopeTable ? scopeTable->get(decl) : nullptr, &decl, scopeTable, {},
-                             decl.parameters, *decl.expr))
+                             decl.parameters, *decl.expr, coverage))
         return std::nullopt;
     return chunk;
 }
 
 std::optional<CompiledChunk> tryCompileStatementExpr(const oscad::Expression& expr, const oscad::Scope* scope,
-                                                      const oscad::ScopeTable* scopeTable) {
+                                                      const oscad::ScopeTable* scopeTable, bool coverage) {
     static const std::vector<std::unique_ptr<oscad::ParameterDeclaration>> kNoParams;
     CompiledChunk chunk;
-    if (!compileFunctionLike(chunk, scope, nullptr, scopeTable, {}, kNoParams, expr)) return std::nullopt;
+    if (!compileFunctionLike(chunk, scope, nullptr, scopeTable, {}, kNoParams, expr, coverage)) return std::nullopt;
     // See this function's own doc comment (bytecode_compiler.hpp) for why a
     // captures-having nested closure can't be supported by this bare
     // wrapper -- selfDecl is nullptr and enclosing is empty above, so its
@@ -1986,7 +2004,7 @@ std::optional<CompiledChunk> tryCompileStatementExpr(const oscad::Expression& ex
 
 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) {
     // Reassignment-warning fidelity (see this function's own doc comment,
     // bytecode_compiler.hpp) -- cheap, one-time scan before touching the
     // compiler at all.
@@ -2002,11 +2020,12 @@ std::optional<CompiledChunk> tryCompileAssignmentBlock(const std::vector<const o
     }
 
     CompiledChunk chunk;
-    Compiler compiler(chunk, scope, nullptr, scopeTable, {});
+    Compiler compiler(chunk, scope, nullptr, scopeTable, {}, coverage);
     CompileScope compileScope;
     compileScope.push();
     try {
         for (const oscad::Assignment* a : assigns) {
+            compiler.cover(chunk.bodyCode, a); // one statement, one hit, same as evalChildren
             compiler.compileExpr(*a->expr, chunk.bodyCode, compileScope); // RHS is never tail
             const std::string& name = a->name->name;
             if (!name.empty() && name[0] == '$') {
@@ -2041,7 +2060,7 @@ std::optional<CompiledChunk> tryCompileAssignmentBlock(const std::vector<const o
 }
 
 std::optional<CompiledChunk> tryCompileModuleBody(const oscad::ModuleDeclaration& decl,
-                                                   const oscad::ScopeTable* scopeTable) {
+                                                   const oscad::ScopeTable* scopeTable, bool coverage) {
     CompiledChunk chunk;
     chunk.isModule = true;
     chunk.selfDecl = &decl;
@@ -2055,7 +2074,7 @@ std::optional<CompiledChunk> tryCompileModuleBody(const oscad::ModuleDeclaration
     // compile path, just scoped to that one statement's own sub-
     // expression -- see this file's own module-chunk doc comment
     // (bytecode.hpp) for the full reasoning.
-    Compiler compiler(chunk, scopeTable ? scopeTable->get(decl) : nullptr, nullptr, scopeTable, {});
+    Compiler compiler(chunk, scopeTable ? scopeTable->get(decl) : nullptr, nullptr, scopeTable, {}, coverage);
     try {
         compiler.compileStatementList(decl.children, chunk.bodyCode);
     } catch (const NotCompilable&) {
@@ -2068,7 +2087,7 @@ std::optional<CompiledChunk> tryCompileModuleBody(const oscad::ModuleDeclaration
 
 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) {
     CompiledChunk chunk;
     // Same completion semantics as a module chunk (no return value, its
     // whole effect is the side effect of what lands in treeStack_) --
@@ -2079,7 +2098,7 @@ std::optional<CompiledChunk> tryCompileChildrenList(const std::vector<const osca
     // ever resolved against it either way; module bodies don't create
     // escaping closures).
     chunk.isModule = true;
-    Compiler compiler(chunk, scope, nullptr, scopeTable, {});
+    Compiler compiler(chunk, scope, nullptr, scopeTable, {}, coverage);
     try {
         compiler.compileStatementList(children, chunk.bodyCode);
     } catch (const NotCompilable&) {