openscad-cpp-evaluator 0.15.0__tar.gz → 0.16.0__tar.gz

{openscad_cpp_evaluator-0.15.0 → openscad_cpp_evaluator-0.16.0}/PKG-INFO

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

{openscad_cpp_evaluator-0.15.0 → openscad_cpp_evaluator-0.16.0}/bindings/CMakeLists.txt

@@ -15,6 +15,7 @@ find_package(nanobind CONFIG REQUIRED)
 # from-source Manifold/Boost rebuild per interpreter in CI.
 nanobind_add_module(_openscad_cpp_evaluator NB_STATIC STABLE_ABI
   module.cpp
+  ast_to_py.cpp
 )
 
 # The static evaluator lib PUBLIC-links parser + manifold + Boost::polygon,

openscad_cpp_evaluator-0.16.0/bindings/ast_to_py.cpp

@@ -0,0 +1,326 @@
+// Snapshots the parser's AST into plain Python dicts.
+//
+// Deliberately a COPY rather than wrappers around live ASTNode pointers.
+// The tree is owned by a `std::vector<std::unique_ptr<ASTNode>>` local to
+// whichever binding parsed it, and dies when that call returns; handing
+// Python raw pointers into it would be a use-after-free the moment anything
+// outlived the call, and this project has already shipped one dangling
+// pointer of exactly that shape (the bodyCtx bug fixed in v0.13.1). It also
+// sidesteps the threading problem entirely -- a render worker thread can
+// parse, hand the snapshot to the GUI thread, and exit, with nothing shared.
+//
+// The cost is one walk plus allocation per parse. That is affordable
+// because callers ask for this explicitly (parse_ast()), not on the render
+// path, which never needs it.
+//
+// Every node dict carries at least:
+//   kind      -- str, the NodeKind name ("NumberLiteral", "ModularCall", ...)
+//   position  -- dict(origin, line, column, start_offset, end_offset)
+// plus that kind's own fields, named in snake_case. Child nodes are nested
+// dicts; child lists are lists of dicts; an absent optional child is None.
+//
+// `position.start_offset`/`end_offset` are the point of the whole exercise:
+// they let a caller recover the ORIGINAL source text of any subexpression
+// and reuse it verbatim, rather than re-serialising a parsed value and
+// losing how the author wrote it (1.500 -> 1.5, 1e3 -> 1000).
+
+#include "openscad_cpp_parser/api.hpp"
+#include "openscad_cpp_parser/ast/ast_node.hpp"
+#include "openscad_cpp_parser/ast/comments.hpp"
+#include "openscad_cpp_parser/ast/declarations.hpp"
+#include "openscad_cpp_parser/ast/expression.hpp"
+#include "openscad_cpp_parser/ast/module_instantiation.hpp"
+#include "openscad_cpp_parser/ast/vector_element.hpp"
+
+#include <nanobind/nanobind.h>
+#include <nanobind/stl/string.h>
+
+#include <memory>
+#include <vector>
+
+namespace nb = nanobind;
+
+namespace oscadbind {
+
+namespace {
+
+nb::dict positionToPy(const oscad::Position& p) {
+    nb::dict d;
+    // origin is "" for the main file (matching how the evaluator reports
+    // it); left as-is rather than mapped to None, so a caller can compare
+    // it against a path without a null check.
+    d["origin"] = p.origin;
+    d["line"] = p.line;
+    d["column"] = p.column;
+    d["start_offset"] = p.start_offset;
+    d["end_offset"] = p.end_offset;
+    return d;
+}
+
+nb::object nodeToPy(const oscad::ASTNode* n);
+
+// A null unique_ptr child (e.g. a parameter with no default) becomes None
+// rather than being omitted, so a consumer can index the key unconditionally.
+template <typename T>
+nb::object childToPy(const std::unique_ptr<T>& p) {
+    return p ? nodeToPy(p.get()) : nb::none();
+}
+
+template <typename T>
+nb::list listToPy(const std::vector<std::unique_ptr<T>>& v) {
+    nb::list out;
+    for (const std::unique_ptr<T>& item : v) out.append(nodeToPy(item.get()));
+    return out;
+}
+
+nb::dict baseDict(const oscad::ASTNode* n) {
+    nb::dict d;
+    d["kind"] = oscad::nodeKindName(n->kind());
+    d["position"] = positionToPy(n->position());
+    return d;
+}
+
+nb::object nodeToPy(const oscad::ASTNode* n) {
+    if (n == nullptr) return nb::none();
+    nb::dict d = baseDict(n);
+
+    // kind() is authoritative about the concrete type (every leaf class sets
+    // its own), so static_cast is safe here and avoids a dynamic_cast per
+    // node on what is already an allocation-heavy walk.
+#define OSC_NODE(KindName, Type) case oscad::NodeKind::KindName: { const auto* x = static_cast<const oscad::Type*>(n); (void)x;
+#define OSC_END break; }
+
+    switch (n->kind()) {
+        // -- comments ---------------------------------------------------
+        OSC_NODE(CommentLine, CommentLine) d["text"] = x->text; OSC_END
+        OSC_NODE(BlankLine, BlankLine) OSC_END
+        OSC_NODE(CommentSpan, CommentSpan) d["text"] = x->text; OSC_END
+        OSC_NODE(CommentedExpr, CommentedExpr)
+            d["leading_comments"] = listToPy(x->leadingComments);
+            d["trailing_comments"] = listToPy(x->trailingComments);
+            d["expr"] = childToPy(x->expr);
+        OSC_END
+
+        // -- primaries / literals ---------------------------------------
+        OSC_NODE(Identifier, Identifier) d["name"] = x->name; OSC_END
+        // `val` is the DECODED string minus its quotes; escape sequences
+        // are kept raw (a source \n stays two characters). Use the span to
+        // recover exactly what was written.
+        OSC_NODE(StringLiteral, StringLiteral) d["val"] = x->val; OSC_END
+        // Parsed to double, so the source spelling (1.500, 1e3, 0x10) is
+        // NOT recoverable from here -- that is what the span is for.
+        OSC_NODE(NumberLiteral, NumberLiteral) d["val"] = x->val; OSC_END
+        OSC_NODE(BooleanLiteral, BooleanLiteral) d["val"] = x->val; OSC_END
+        OSC_NODE(UndefinedLiteral, UndefinedLiteral) OSC_END
+        OSC_NODE(RangeLiteral, RangeLiteral)
+            d["start"] = childToPy(x->start);
+            d["end"] = childToPy(x->end);
+            // Never null: the parser defaults an omitted step to 1.
+            d["step"] = childToPy(x->step);
+        OSC_END
+
+        // -- declarations / arguments -----------------------------------
+        OSC_NODE(ParameterDeclaration, ParameterDeclaration)
+            d["name"] = childToPy(x->name);
+            d["default_value"] = childToPy(x->defaultValue); // nullable
+            d["leading_comments"] = listToPy(x->leadingComments);
+            d["trailing_comments"] = listToPy(x->trailingComments);
+        OSC_END
+        OSC_NODE(PositionalArgument, PositionalArgument) d["expr"] = childToPy(x->expr); OSC_END
+        OSC_NODE(NamedArgument, NamedArgument)
+            d["name"] = childToPy(x->name);
+            d["expr"] = childToPy(x->expr);
+        OSC_END
+        OSC_NODE(Assignment, Assignment)
+            d["name"] = childToPy(x->name);
+            d["expr"] = childToPy(x->expr);
+        OSC_END
+
+        // -- prefix expression forms ------------------------------------
+        OSC_NODE(LetOp, LetOp)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(EchoOp, EchoOp)
+            d["arguments"] = listToPy(x->arguments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(AssertOp, AssertOp)
+            d["arguments"] = listToPy(x->arguments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(FunctionLiteral, FunctionLiteral)
+            d["parameters"] = listToPy(x->parameters);
+            d["body"] = childToPy(x->body);
+        OSC_END
+
+        // -- unary operators --------------------------------------------
+#define OSC_UNARY(KindName) OSC_NODE(KindName, KindName) d["expr"] = childToPy(x->expr); OSC_END
+        OSC_UNARY(UnaryMinusOp)
+        OSC_UNARY(LogicalNotOp)
+        OSC_UNARY(BitwiseNotOp)
+#undef OSC_UNARY
+
+        // -- binary operators -------------------------------------------
+#define OSC_BINARY(KindName)                                                                                          \
+    OSC_NODE(KindName, KindName) d["left"] = childToPy(x->left); d["right"] = childToPy(x->right); OSC_END
+        OSC_BINARY(AdditionOp)
+        OSC_BINARY(SubtractionOp)
+        OSC_BINARY(MultiplicationOp)
+        OSC_BINARY(DivisionOp)
+        OSC_BINARY(ModuloOp)
+        OSC_BINARY(ExponentOp)
+        OSC_BINARY(BitwiseAndOp)
+        OSC_BINARY(BitwiseOrOp)
+        OSC_BINARY(BitwiseShiftLeftOp)
+        OSC_BINARY(BitwiseShiftRightOp)
+        OSC_BINARY(LogicalAndOp)
+        OSC_BINARY(LogicalOrOp)
+        OSC_BINARY(EqualityOp)
+        OSC_BINARY(InequalityOp)
+        OSC_BINARY(GreaterThanOp)
+        OSC_BINARY(GreaterThanOrEqualOp)
+        OSC_BINARY(LessThanOp)
+        OSC_BINARY(LessThanOrEqualOp)
+#undef OSC_BINARY
+
+        OSC_NODE(TernaryOp, TernaryOp)
+            d["condition"] = childToPy(x->condition);
+            d["true_expr"] = childToPy(x->trueExpr);
+            d["false_expr"] = childToPy(x->falseExpr);
+        OSC_END
+
+        // -- postfix ----------------------------------------------------
+        OSC_NODE(PrimaryCall, PrimaryCall)
+            d["left"] = childToPy(x->left);
+            d["arguments"] = listToPy(x->arguments);
+        OSC_END
+        OSC_NODE(PrimaryIndex, PrimaryIndex)
+            d["left"] = childToPy(x->left);
+            d["index"] = childToPy(x->index);
+        OSC_END
+        OSC_NODE(PrimaryMember, PrimaryMember)
+            d["left"] = childToPy(x->left);
+            d["member"] = childToPy(x->member);
+        OSC_END
+
+        // -- list comprehension clauses ---------------------------------
+        OSC_NODE(ListCompLet, ListCompLet)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(ListCompEach, ListCompEach) d["body"] = childToPy(x->body); OSC_END
+        OSC_NODE(ListCompFor, ListCompFor)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(ListCompCFor, ListCompCFor)
+            d["inits"] = listToPy(x->inits);
+            d["condition"] = childToPy(x->condition);
+            d["incrs"] = listToPy(x->incrs);
+            d["body"] = childToPy(x->body);
+        OSC_END
+        OSC_NODE(ListCompIf, ListCompIf)
+            d["condition"] = childToPy(x->condition);
+            d["true_expr"] = childToPy(x->trueExpr);
+        OSC_END
+        OSC_NODE(ListCompIfElse, ListCompIfElse)
+            d["condition"] = childToPy(x->condition);
+            d["true_expr"] = childToPy(x->trueExpr);
+            d["false_expr"] = childToPy(x->falseExpr);
+        OSC_END
+        // Also how a plain vector literal ([1,2,3]) is represented --
+        // elements mix comprehension clauses and bare expressions.
+        OSC_NODE(ListComprehension, ListComprehension) d["elements"] = listToPy(x->elements); OSC_END
+
+        // -- module instantiation ---------------------------------------
+        OSC_NODE(ModularCall, ModularCall)
+            d["name"] = childToPy(x->name);
+            d["arguments"] = listToPy(x->arguments);
+            d["children"] = listToPy(x->children);
+        OSC_END
+        OSC_NODE(ModularFor, ModularFor)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = listToPy(x->body);
+        OSC_END
+        OSC_NODE(ModularIntersectionFor, ModularIntersectionFor)
+            d["assignments"] = listToPy(x->assignments);
+            d["body"] = listToPy(x->body);
+        OSC_END
+        OSC_NODE(ModularLet, ModularLet)
+            d["assignments"] = listToPy(x->assignments);
+            d["children"] = listToPy(x->children);
+        OSC_END
+        OSC_NODE(ModularEcho, ModularEcho)
+            d["arguments"] = listToPy(x->arguments);
+            d["children"] = listToPy(x->children);
+        OSC_END
+        OSC_NODE(ModularAssert, ModularAssert)
+            d["arguments"] = listToPy(x->arguments);
+            d["children"] = listToPy(x->children);
+        OSC_END
+        OSC_NODE(ModularIf, ModularIf)
+            d["condition"] = childToPy(x->condition);
+            d["true_branch"] = listToPy(x->trueBranch);
+        OSC_END
+        OSC_NODE(ModularIfElse, ModularIfElse)
+            d["condition"] = childToPy(x->condition);
+            d["true_branch"] = listToPy(x->trueBranch);
+            d["false_branch"] = listToPy(x->falseBranch);
+        OSC_END
+
+        // -- modifier wrappers (! # % *) --------------------------------
+#define OSC_MODIFIER(KindName) OSC_NODE(KindName, KindName) d["child"] = childToPy(x->child); OSC_END
+        OSC_MODIFIER(ModularModifierShowOnly)
+        OSC_MODIFIER(ModularModifierHighlight)
+        OSC_MODIFIER(ModularModifierBackground)
+        OSC_MODIFIER(ModularModifierDisable)
+#undef OSC_MODIFIER
+
+        // -- top-level declarations -------------------------------------
+        OSC_NODE(ModuleDeclaration, ModuleDeclaration)
+            d["name"] = childToPy(x->name);
+            d["parameters"] = listToPy(x->parameters);
+            d["children"] = listToPy(x->children);
+            d["pre_name_comments"] = listToPy(x->preNameComments);
+            d["post_name_comments"] = listToPy(x->postNameComments);
+            d["post_params_comments"] = listToPy(x->postParamsComments);
+        OSC_END
+        OSC_NODE(FunctionDeclaration, FunctionDeclaration)
+            d["name"] = childToPy(x->name);
+            d["parameters"] = listToPy(x->parameters);
+            d["expr"] = childToPy(x->expr);
+            d["pre_name_comments"] = listToPy(x->preNameComments);
+            d["post_name_comments"] = listToPy(x->postNameComments);
+            d["post_params_comments"] = listToPy(x->postParamsComments);
+        OSC_END
+        OSC_NODE(UseStatement, UseStatement) d["filepath"] = childToPy(x->filepath); OSC_END
+        OSC_NODE(IncludeStatement, IncludeStatement) d["filepath"] = childToPy(x->filepath); OSC_END
+    }
+
+#undef OSC_NODE
+#undef OSC_END
+
+    // No default: above -- the switch is exhaustive over NodeKind, so
+    // adding a node kind to the parser without handling it here is a
+    // compiler warning rather than a silently field-less dict.
+    return d;
+}
+
+} // namespace
+
+nb::list astToPy(const std::vector<std::unique_ptr<oscad::ASTNode>>& ast) {
+    nb::list out;
+    for (const std::unique_ptr<oscad::ASTNode>& n : ast) out.append(nodeToPy(n.get()));
+    return out;
+}
+
+nb::list parseAstFromFile(const std::string& path, bool includeComments) {
+    return astToPy(oscad::getASTFromFile(path, includeComments));
+}
+
+nb::list parseAstFromString(const std::string& code, bool includeComments) {
+    return astToPy(oscad::getASTFromString(code, includeComments));
+}
+
+} // namespace oscadbind

{openscad_cpp_evaluator-0.15.0 → openscad_cpp_evaluator-0.16.0}/bindings/module.cpp

@@ -40,6 +40,14 @@
 
 namespace nb = nanobind;
 
+// Defined in ast_to_py.cpp -- snapshots the parser's AST into plain Python
+// dicts. Declared here rather than in a header since these two entry points
+// are the whole interface and only this file calls them.
+namespace oscadbind {
+nb::list parseAstFromFile(const std::string& path, bool includeComments);
+nb::list parseAstFromString(const std::string& code, bool includeComments);
+} // namespace oscadbind
+
 namespace {
 
 // Moves a std::vector's storage into a NumPy array that owns it via a
@@ -649,6 +657,12 @@ NB_MODULE(_openscad_cpp_evaluator, m) {
           "Evaluate a .scad file; return (bodies, echoes, id_to_node, csg_tree, profile_result, dyn, dyn_explicit).");
     m.def("parse_decls", &parseDecls, nb::arg("path"),
           "Parse a .scad file; return top-level declaration (namespace, name, start, end, line, column, origin) tuples.");
+    m.def("parse_ast", &oscadbind::parseAstFromFile, nb::arg("path"), nb::arg("include_comments") = false,
+          "Parse a .scad file; return the AST as a list of plain nested dicts "
+          "(kind, position, plus that kind's own fields). A snapshot, not a view -- "
+          "safe to keep, share across threads, and outlive the parse.");
+    m.def("parse_ast_string", &oscadbind::parseAstFromString, nb::arg("code"), nb::arg("include_comments") = false,
+          "As parse_ast(), but parses a source string instead of a file.");
     m.def("debug_evaluate", &debugEvaluate, nb::arg("path"), nb::arg("viewport_params"), nb::arg("debug_hook"),
           nb::arg("error_break"), nb::arg("echo_fn"), nb::arg("manifold_cache") = nullptr,
           nb::arg("return_hook") = nb::none(), nb::arg("fast_continue_signal") = nullptr,

{openscad_cpp_evaluator-0.15.0 → openscad_cpp_evaluator-0.16.0}/pyproject.toml

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

{openscad_cpp_evaluator-0.15.0 → openscad_cpp_evaluator-0.16.0}/python/openscad_cpp_evaluator/__init__.py

@@ -18,7 +18,7 @@ from ._openscad_cpp_evaluator import FastContinueSignal, ManifoldCache
 __all__ = [
     "Evaluator", "ColoredBody", "EvalError", "ParseError", "OscObject", "parse", "to_renderable_bodies",
     "ManifoldCache", "CallSiteProfile", "ProfileResult", "format_csg_tree", "bodies_from_dicts",
-    "FastContinueSignal",
+    "FastContinueSignal", "parse_ast", "parse_ast_string",
 ]
 
 
@@ -256,6 +256,41 @@ def parse(path: str) -> RootScope:
     return RootScope(decls)
 
 
+def parse_ast(path: str, include_comments: bool = False) -> list:
+    """Parse a .scad file; return its AST as a list of plain nested dicts.
+
+    Each node is `{"kind": str, "position": {...}, **fields}`, where fields
+    are that kind's own (e.g. NumberLiteral has "val"; ModularCall has
+    "name"/"arguments"/"children"). Child nodes nest as dicts, child lists
+    as lists, and an absent optional child is None.
+
+    `position` carries `start_offset`/`end_offset`, which is the point of
+    this API: they let a caller slice the ORIGINAL source text of any
+    subexpression and reuse it verbatim, instead of re-serialising a parsed
+    value and losing how it was written (`1.500` -> `1.5`, `1e3` -> `1000`).
+
+    This is a SNAPSHOT, not a view of live parser memory: it is safe to
+    keep, mutate, share across threads, and outlive the parse. That costs
+    one walk per call, which is why it is a separate entry point rather
+    than something evaluate() always pays for.
+
+    Raises ParseError on a syntax error.
+    """
+    try:
+        return _ext.parse_ast(path, include_comments)
+    except Exception as e:
+        raise ParseError(str(e)) from e
+
+
+def parse_ast_string(code: str, include_comments: bool = False) -> list:
+    """As `parse_ast`, but parses a source string. `position.origin` is
+    "<string>" for every node. Raises ParseError on a syntax error."""
+    try:
+        return _ext.parse_ast_string(code, include_comments)
+    except Exception as e:
+        raise ParseError(str(e)) from e
+
+
 class _MeshShim:
     """Duck-types a manifold3d mesh: the four arrays the renderer reads."""
     __slots__ = ("vert_properties", "tri_verts", "run_original_id", "run_index", "num_prop")

{openscad_cpp_evaluator-0.15.0 → openscad_cpp_evaluator-0.16.0}/tests/test_python_bindings.py

@@ -232,6 +232,122 @@ def test_role_defaults_to_normal_and_reflects_modifiers():
     assert roles == ["highlight", "show_only"]
 
 
+# -- parse_ast: AST snapshot ---------------------------------------------
+
+
+def test_parse_ast_spans_recover_original_number_text():
+    # The whole point of exposing spans: a parsed NumberLiteral is a double,
+    # so the source spelling is gone from `val` -- but the span still points
+    # at it, letting a rewriter reuse the author's own text verbatim.
+    from openscad_cpp_evaluator import parse_ast_string
+    src = "translate([1.500, 2.250, 1e3]) cube(2);"
+    vec = parse_ast_string(src)[0]["arguments"][0]["expr"]
+    spellings = [src[e["position"]["start_offset"]:e["position"]["end_offset"]] for e in vec["elements"]]
+    assert spellings == ["1.500", "2.250", "1e3"], spellings
+    assert [e["val"] for e in vec["elements"]] == [1.5, 2.25, 1000.0]
+
+
+def test_parse_ast_node_shapes():
+    from openscad_cpp_evaluator import parse_ast_string
+    ast = parse_ast_string("module m(a, b=2) { cube(a); } m(1, b=3) sphere(2);")
+    decl, call = ast
+    assert decl["kind"] == "ModuleDeclaration"
+    assert decl["name"]["name"] == "m"
+    assert [p["name"]["name"] for p in decl["parameters"]] == ["a", "b"]
+    # An absent optional child is None, not a missing key.
+    assert decl["parameters"][0]["default_value"] is None
+    assert decl["parameters"][1]["default_value"]["val"] == 2.0
+    assert call["kind"] == "ModularCall"
+    assert [a["kind"] for a in call["arguments"]] == ["PositionalArgument", "NamedArgument"]
+    assert call["arguments"][1]["name"]["name"] == "b"
+    assert [c["kind"] for c in call["children"]] == ["ModularCall"]
+
+
+def test_parse_ast_covers_every_node_kind_reachable_from_source():
+    # Guards the exhaustive switch in ast_to_py.cpp: a node kind added to
+    # the parser without a case here would produce a dict with only
+    # kind/position, silently losing its fields.
+    from openscad_cpp_evaluator import parse_ast_string
+    src = """
+    include <x.scad>
+    use <y.scad>
+    A = 1; B = "s"; C = true; D = undef; E = [0:2:10]; F = -A; G = !C; H = ~1;
+    I = A+1-2*3/4%5^2; J = A<1 && A>2 || A<=3 && A>=4 && A==5 && A!=6;
+    K = A&1 | 2 << 3 >> 4;
+    L = C ? A : B; M = [1,2,3][0]; N = let(x=1) x; O = echo("e") 1;
+    P = assert(true) 2; Q = function(a) a; R = [for (i=[0:3]) i*2];
+    S = [for (i=[0:3]) if (i%2==0) i else -i];
+    S2 = [for (i=[0:3]) if (i%2==0) i];              // bare if -> ListCompIf
+    T = [for (i=0; i<3; i=i+1) i]; U = [for (v=[[1,2]]) each v];
+    V = [let(z=2) for (i=[0:1]) z*i]; W = object(a=1).a;
+    function fn(p) = p; module mod(m) { cube(m); children(); }
+    mod(1) { sphere(2); }
+    for (i=[0:1]) cube(1);
+    intersection_for (i=[0:1]) cube(2);
+    let (t=1) cube(t); echo("hi") cube(1); assert(true) cube(1);
+    if (A>0) cube(1); else sphere(1);
+    if (A>0) cube(1);                                 // bare if -> ModularIf
+    !cube(1); #cube(1); %cube(1); *cube(1);
+    """
+    seen = set()
+
+    def walk(n):
+        if isinstance(n, dict) and "kind" in n:
+            seen.add(n["kind"])
+            pos = n["position"]
+            assert pos["end_offset"] >= pos["start_offset"], n["kind"]
+            for k, v in n.items():
+                if k not in ("kind", "position"):
+                    walk(v)
+        elif isinstance(n, list):
+            for x in n:
+                walk(x)
+
+    for node in parse_ast_string(src, True):
+        walk(node)
+    # Every kind above, minus the three only produced by comment
+    # preservation on a file with comments in the right places.
+    expected = {
+        "IncludeStatement", "UseStatement", "Assignment", "Identifier", "NumberLiteral", "StringLiteral",
+        "BooleanLiteral", "UndefinedLiteral", "RangeLiteral", "UnaryMinusOp", "LogicalNotOp", "BitwiseNotOp",
+        "AdditionOp", "SubtractionOp", "MultiplicationOp", "DivisionOp", "ModuloOp", "ExponentOp",
+        "BitwiseAndOp", "BitwiseOrOp", "BitwiseShiftLeftOp", "BitwiseShiftRightOp", "LogicalAndOp",
+        "LogicalOrOp", "EqualityOp", "InequalityOp", "GreaterThanOp", "GreaterThanOrEqualOp", "LessThanOp",
+        "LessThanOrEqualOp", "TernaryOp", "PrimaryCall", "PrimaryIndex", "PrimaryMember", "LetOp", "EchoOp",
+        "AssertOp", "FunctionLiteral", "ListComprehension", "ListCompFor", "ListCompIf", "ListCompIfElse",
+        "ListCompCFor", "ListCompEach", "ListCompLet", "FunctionDeclaration", "ModuleDeclaration",
+        "ParameterDeclaration", "PositionalArgument", "NamedArgument", "ModularCall", "ModularFor",
+        "ModularIntersectionFor", "ModularLet", "ModularEcho", "ModularAssert", "ModularIf", "ModularIfElse",
+        "ModularModifierShowOnly", "ModularModifierHighlight", "ModularModifierBackground",
+        "ModularModifierDisable",
+    }
+    missing = expected - seen
+    assert not missing, f"node kinds not emitted: {sorted(missing)}"
+
+
+def test_parse_ast_snapshot_outlives_the_parse():
+    # It is a copy, not a view into parser memory -- the point of the
+    # snapshot design. Holding it after many further parses (which reuse
+    # and free the same arenas) must not corrupt it.
+    from openscad_cpp_evaluator import parse_ast_string
+    held = parse_ast_string("a = 1.500;")
+    for i in range(200):
+        parse_ast_string(f"b{i} = [for (j=[0:20]) j*{i}];")
+    assert held[0]["expr"]["val"] == 1.5
+    assert held[0]["name"]["name"] == "a"
+    held[0]["expr"]["val"] = 99.0  # plain dicts: mutable, owned by the caller
+    assert held[0]["expr"]["val"] == 99.0
+
+
+def test_parse_ast_raises_parse_error_on_bad_syntax():
+    from openscad_cpp_evaluator import ParseError, parse_ast_string
+    try:
+        parse_ast_string("cube(")
+    except ParseError:
+        return
+    raise AssertionError("expected ParseError")
+
+
 def main():
     tests = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
     failures = []