openscad-cpp-evaluator 1.3.1__tar.gz → 1.4.0__tar.gz

{openscad_cpp_evaluator-1.3.1 → openscad_cpp_evaluator-1.4.0}/PKG-INFO

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

{openscad_cpp_evaluator-1.3.1 → openscad_cpp_evaluator-1.4.0}/bindings/module.cpp

@@ -388,8 +388,8 @@ nb::object evaluate(const std::string& path, nb::dict viewportParams,
         nb::gil_scoped_release rel;
         auto logFn = [&echoes](const std::string& m) { echoes.push_back(m); };
         try {
-            std::vector<std::unique_ptr<oscad::ASTNode>> ast = oscad::getASTFromFile(path);
-            oscadeval::ResolvedUseScopes used = oscadeval::resolveUseScopes(ast, path, logFn);
+            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::EvalContext ctx = oscadeval::EvalContext::makeRoot(used.rootScope.get());
             bodies = oscadeval::toRenderableBodies(ev.evaluate(used.processedNodes, ctx, vp, generate));
@@ -693,8 +693,8 @@ nb::object debugEvaluate(const std::string& path, nb::dict viewportParams, nb::c
             };
         }
         try {
-            std::vector<std::unique_ptr<oscad::ASTNode>> ast = oscad::getASTFromFile(path);
-            oscadeval::ResolvedUseScopes used = oscadeval::resolveUseScopes(ast, path, echoCpp);
+            oscad::ParsedProgram program = oscad::getProgramFromFile(path);
+            oscadeval::ResolvedUseScopes used = oscadeval::resolveUseScopes(program.nodes, path, echoCpp);
             oscadeval::Evaluator ev(echoCpp, nullptr, manifoldCache, hooks, false);
             evPtr = &ev;
             if (fastContinueSignal) ev.setFastContinueInterruptFlag(fastContinueSignal->flag());
@@ -729,8 +729,8 @@ nb::list parseDecls(const std::string& path) {
     std::vector<Decl> decls;
     {
         nb::gil_scoped_release rel;
-        std::vector<std::unique_ptr<oscad::ASTNode>> ast = oscad::getASTFromFile(path);
-        oscadeval::ResolvedUseScopes used = oscadeval::resolveUseScopes(ast, path, [](const std::string&) {});
+        oscad::ParsedProgram program = oscad::getProgramFromFile(path);
+        oscadeval::ResolvedUseScopes used = oscadeval::resolveUseScopes(program.nodes, path, [](const std::string&) {});
         for (const oscad::ASTNode* n : used.processedNodes) {
             const oscad::Position& p = n->position();
             const char* ns = nullptr;

{openscad_cpp_evaluator-1.3.1 → openscad_cpp_evaluator-1.4.0}/external/openscad_cpp_parser/include/openscad_cpp_parser/api.hpp

@@ -1,6 +1,7 @@
 #pragma once
 
 #include "openscad_cpp_parser/ast.hpp"
+#include "openscad_cpp_parser/scope_table.hpp"
 #include "openscad_cpp_parser/source_map.hpp"
 
 #include <memory>
@@ -68,15 +69,10 @@ std::vector<std::unique_ptr<ASTNode>> getASTFromString(const std::string& code,
 // can't be found/read, or ParseError (see getASTFromString) on a syntax
 // error in any of the involved files.
 //
-// ponytail: unlike the Python reference, this does NOT cache parsed ASTs
-// (in-memory or on-disk) across calls. With unique_ptr ownership, "return
-// the same cached tree to every caller" isn't representable (each caller
-// needs exclusive ownership), and a clone-based cache would need a deep
-// clone() for all 66 node kinds just to support an unmeasured perf
-// optimization. Every call re-parses. Upgrade path: add a per-node
-// clone() (mirroring toJson/toString's per-kind dispatch) and cache
-// serialized snapshots keyed by (path, mtime) if repeated-parse cost of a
-// real workload is shown to matter.
+// This does NOT share or cache anything: every call re-parses the file and
+// every file it includes, and the caller owns all of it. See
+// getProgramFromFile() for the shared, cached form -- the one an evaluator
+// that re-renders the same script should use.
 std::vector<std::unique_ptr<ASTNode>> getASTFromFile(const std::string& file, bool includeComments = false,
                                                       bool processIncludes = true);
 
@@ -95,9 +91,44 @@ LibraryFileResult getASTFromLibraryFile(const std::string& currFile, const std::
 // platform default library dir.
 std::optional<std::string> findLibraryFile(const std::string& currFile, const std::string& libFile);
 
-// No-op: kept for API-shape parity with the Python reference's
-// clear_ast_cache(). See the ponytail note on getASTFromFile() -- this
-// port doesn't cache, so there's nothing to clear.
+// A file's statements with its `include <...>` directives resolved, where
+// each included file's AST is SHARED with every other file that includes
+// it rather than re-parsed.
+//
+// That sharing is the point. Parsing `include <BOSL2/std.scad>` costs
+// ~55ms and is ~82% of evaluating a small BOSL2 script; the library does
+// not change between renders, so re-parsing it every time is the single
+// largest cost in a re-render or a docs build (which renders ~1000
+// examples, each including the same library).
+//
+// Only the per-FILE parses are cached, not a whole resolved program: a
+// file is spliced in at most once per resolution (`visited`), so caching
+// std.scad already-resolved would double its statements in a script that
+// also includes something else depending on it. Re-running the resolution
+// is only pointer pushes.
+struct ParsedProgram {
+    // The flattened statement list, in source order, includes spliced in
+    // where their directives stood. Non-owning: see keepAlive.
+    std::vector<const ASTNode*> nodes;
+    // Holds every AST the above points into -- this file's own parse and
+    // each shared include -- alive for as long as this object. Nodes are
+    // borrowed, never owned, which is what lets two scripts (or two
+    // threads) use the same parsed library at once.
+    std::vector<std::shared_ptr<const std::vector<std::unique_ptr<ASTNode>>>> keepAlive;
+};
+
+// Parses `file` and resolves its includes against the cache, which is keyed
+// by (path, mtime, size) so an edited file re-parses on its own.
+// Thread-safe. Throws exactly as getASTFromFile does.
+ParsedProgram getProgramFromFile(const std::string& file, bool includeComments = false);
+
+// Drops every cached file parse. Nothing already handed out is
+// invalidated -- a ParsedProgram keeps what it borrowed alive.
 void clearAstCache();
 
+// How many file parses the cache is holding. For tests that need to prove
+// the cache replaces an edited file's entry rather than accumulating one
+// per save.
+size_t astCacheSize();
+
 } // namespace oscad

openscad_cpp_evaluator-1.4.0/external/openscad_cpp_parser/include/openscad_cpp_parser/ast/ast_node.hpp

@@ -0,0 +1,213 @@
+#pragma once
+
+#include "openscad_cpp_parser/position.hpp"
+
+#include <cstdint>
+#include <string>
+
+namespace oscad {
+
+class Scope;
+
+// One value per instantiable (leaf) AST node class. Abstract bases
+// (Expression, Primary, Argument, VectorElement, ModuleInstantiation) have
+// no NodeKind of their own, since they are never directly constructed.
+enum class NodeKind {
+    // Comments
+    CommentLine,
+    BlankLine,
+    CommentSpan,
+    CommentedExpr,
+    // Primary / literals
+    Identifier,
+    StringLiteral,
+    NumberLiteral,
+    BooleanLiteral,
+    UndefinedLiteral,
+    RangeLiteral,
+    // Declarations / arguments
+    ParameterDeclaration,
+    PositionalArgument,
+    NamedArgument,
+    Assignment,
+    // Prefix expression forms
+    LetOp,
+    EchoOp,
+    AssertOp,
+    FunctionLiteral,
+    // Operators
+    UnaryMinusOp,
+    AdditionOp,
+    SubtractionOp,
+    MultiplicationOp,
+    DivisionOp,
+    ModuloOp,
+    ExponentOp,
+    BitwiseAndOp,
+    BitwiseOrOp,
+    BitwiseNotOp,
+    BitwiseShiftLeftOp,
+    BitwiseShiftRightOp,
+    LogicalAndOp,
+    LogicalOrOp,
+    LogicalNotOp,
+    TernaryOp,
+    EqualityOp,
+    InequalityOp,
+    GreaterThanOp,
+    GreaterThanOrEqualOp,
+    LessThanOp,
+    LessThanOrEqualOp,
+    // Postfix
+    PrimaryCall,
+    PrimaryIndex,
+    PrimaryMember,
+    // render() in EXPRESSION position -- evaluates its children as geometry
+    // and yields an object() of measurements. The STATEMENT form of render()
+    // is a plain ModularCall named "render"; only this one is new.
+    RenderExpression,
+    // List comprehension
+    ListCompLet,
+    ListCompEach,
+    ListCompFor,
+    ListCompCFor,
+    ListCompIf,
+    ListCompIfElse,
+    ListComprehension,
+    // Module instantiation
+    ModularCall,
+    ModularFor,
+    ModularIntersectionFor,
+    ModularLet,
+    ModularEcho,
+    ModularAssert,
+    ModularIf,
+    ModularIfElse,
+    ModularModifierShowOnly,
+    ModularModifierHighlight,
+    ModularModifierBackground,
+    ModularModifierDisable,
+    // Top-level declarations
+    ModuleDeclaration,
+    FunctionDeclaration,
+    UseStatement,
+    IncludeStatement,
+};
+
+const char* nodeKindName(NodeKind kind);
+
+// Base class for all AST nodes. Mirrors openscad_lalr_parser.nodes.ASTNode:
+// every node carries its source Position and (once buildScope() has run) a
+// non-owning pointer to the Scope visible at that point in the tree.
+// Numbering context for the nodes one parse creates: every node built
+// while it is installed gets that parse's treeId and a slot dense within
+// it -- see ASTNode::slot().
+struct NodeNumbering {
+    uint32_t treeId = 0;
+    uint32_t next = 0;
+};
+
+// Installs a numbering for a whole parse, INCLUDING any pass that builds
+// more nodes from its result (attachComments wraps expressions in
+// CommentedExpr nodes after the parser proper has finished). Nested use
+// reuses the outer numbering rather than starting a second one, so a tree
+// stays a tree however many passes contribute to it.
+//
+// Thread-local: two threads may parse at once and must number
+// independently.
+class ParseNumberingScope {
+public:
+    ParseNumberingScope();
+    ~ParseNumberingScope();
+    ParseNumberingScope(const ParseNumberingScope&) = delete;
+    ParseNumberingScope& operator=(const ParseNumberingScope&) = delete;
+
+private:
+    NodeNumbering numbering_;
+    NodeNumbering* previous_;
+    bool installed_;
+};
+
+class ScopeTable;
+
+// The table setScope() writes into. buildScopes() installs one for its
+// walk; thread-local, so two evaluations can build scopes at once over the
+// same shared tree -- the whole point of sharing it.
+class ScopeTableScope {
+public:
+    explicit ScopeTableScope(ScopeTable& table);
+    ~ScopeTableScope();
+    ScopeTableScope(const ScopeTableScope&) = delete;
+    ScopeTableScope& operator=(const ScopeTableScope&) = delete;
+
+private:
+    ScopeTable* previous_;
+};
+
+NodeNumbering* currentNodeNumbering();
+// Slot for a node built with no parse active -- a test constructing nodes
+// by hand, or astFromJson. Those all land in treeId 0 with process-unique
+// slots, so they never collide with each other.
+uint32_t nextLooseSlot();
+
+class ASTNode {
+public:
+    ASTNode(NodeKind kind, Position position) : kind_(kind), position_(std::move(position)) {
+        if (NodeNumbering* n = currentNodeNumbering()) {
+            treeId_ = n->treeId;
+            slot_ = n->next++;
+        } else {
+            slot_ = nextLooseSlot();
+        }
+    }
+    virtual ~ASTNode() = default;
+
+    ASTNode(const ASTNode&) = delete;
+    ASTNode& operator=(const ASTNode&) = delete;
+
+    NodeKind kind() const { return kind_; }
+    const Position& position() const { return position_; }
+
+    // Identity of the parse that built this node, and this node's dense
+    // index within it. Together they address the node's Scope in a
+    // ScopeTable, which is what lets one parsed tree be shared by several
+    // evaluations at once: the scope a node sits in depends on the file
+    // that included it, so it cannot live in the node itself. Both are 0
+    // for a node built outside a parse (a test constructing nodes by
+    // hand), which is a valid single tree of its own.
+    uint32_t treeId() const { return treeId_; }
+    uint32_t slot() const { return slot_; }
+
+    // A node's Scope is NOT stored here -- it lives in the render's
+    // ScopeTable, addressed by (treeId, slot). It has to: one parsed tree
+    // is shared by every script that includes it, and `include` means the
+    // included nodes sit in the INCLUDER's scope, so the same node is in a
+    // different scope in each. Read it with ScopeTable::get(node).
+
+    // Mirrors Python's __str__: every leaf node overrides this.
+    virtual std::string toString() const = 0;
+
+    // Mirrors Python's build_scope(parent_scope): the default (leaf) case
+    // just records parent_scope; nodes that introduce bindings or new
+    // scopes override this.
+    virtual void buildScope(Scope& parentScope) { setScope(parentScope); }
+
+protected:
+    // For buildScope() overrides: records the scope visible at this node,
+    // mirroring Python's `self.scope = parent_scope` (which is often a
+    // *different* scope than what gets passed to this node's children).
+    //
+    // Writes into the ScopeTable buildScopes() installed for the duration
+    // of its walk, rather than taking one as a parameter: that keeps all
+    // 37 buildScope() overrides on their existing signature, and the walk
+    // is a single scoped pass with nothing else running inside it.
+    void setScope(Scope& s);
+
+private:
+    NodeKind kind_;
+    Position position_;
+    uint32_t treeId_ = 0;
+    uint32_t slot_ = 0;
+};
+
+} // namespace oscad

{openscad_cpp_evaluator-1.3.1 → openscad_cpp_evaluator-1.4.0}/external/openscad_cpp_parser/include/openscad_cpp_parser/ast.hpp

@@ -7,6 +7,7 @@
 #include "openscad_cpp_parser/ast/expression.hpp"
 #include "openscad_cpp_parser/ast/module_instantiation.hpp"
 #include "openscad_cpp_parser/ast/scope_builder.hpp"
+#include "openscad_cpp_parser/scope_table.hpp"
 #include "openscad_cpp_parser/ast/vector_element.hpp"
 #include "openscad_cpp_parser/position.hpp"
 #include "openscad_cpp_parser/scope.hpp"

{openscad_cpp_evaluator-1.3.1 → openscad_cpp_evaluator-1.4.0}/external/openscad_cpp_parser/include/openscad_cpp_parser/scope.hpp

@@ -1,5 +1,7 @@
 #pragma once
 
+#include "openscad_cpp_parser/scope_table.hpp"
+
 #include <memory>
 #include <string>
 #include <unordered_map>
@@ -83,6 +85,19 @@ public:
         return *children_.back();
     }
 
+    // The ScopeTable holding every node's scope for this scope tree.
+    // buildScopes() attaches it to the root it returns, so the table lives
+    // exactly as long as the scopes it points at -- which is the ownership
+    // contract callers already keep. Null on a non-root scope; use
+    // rootTable() to reach it from anywhere in the tree.
+    void adoptTable(std::unique_ptr<ScopeTable> table);
+    const ScopeTable* table() const { return ownedTable_.get(); }
+    const ScopeTable* rootTable() const {
+        const Scope* s = this;
+        while (s->parent_) s = s->parent_;
+        return s->ownedTable_.get();
+    }
+
 private:
     static ASTNode* find(const std::unordered_map<std::string, ASTNode*>& table, const std::string& name) {
         auto it = table.find(name);
@@ -94,6 +109,16 @@ private:
     std::unordered_map<std::string, ASTNode*> functions_;
     std::unordered_map<std::string, ASTNode*> modules_;
     std::vector<std::unique_ptr<Scope>> children_;
+    std::unique_ptr<ScopeTable> ownedTable_;   // root only
 };
 
+// The lexical Scope recorded for `node` when `anyScopeInTree`'s tree was
+// built -- the replacement for the ASTNode::scope() field that used to
+// live in the node. Any scope in the tree will do; it walks up to the root
+// that owns the table.
+inline const Scope* scopeOf(const Scope& anyScopeInTree, const ASTNode& node) {
+    const ScopeTable* table = anyScopeInTree.rootTable();
+    return table ? table->get(node) : nullptr;
+}
+
 } // namespace oscad

openscad_cpp_evaluator-1.4.0/external/openscad_cpp_parser/include/openscad_cpp_parser/scope_table.hpp

@@ -0,0 +1,58 @@
+#pragma once
+
+#include "openscad_cpp_parser/ast/ast_node.hpp"
+
+#include <cstdint>
+#include <vector>
+
+namespace oscad {
+
+class Scope;
+
+// Where a node's Scope lives, now that it cannot live in the node.
+//
+// A parsed tree is shared: `include <BOSL2/std.scad>` is parsed once and
+// then handed to every script that includes it, which is what makes a
+// render cheap (parsing BOSL2 is ~55ms and dwarfs everything else). But
+// `include` means "share my scope", so the very same BOSL2 node sits in a
+// different scope in every script that includes it. A `Scope*` field in
+// ASTNode could only ever hold one of them, and whichever render wrote it
+// last would corrupt the others.
+//
+// So the pointer moves out here, into a table one render owns. Addressing
+// is (treeId, slot), both stamped on the node when it was parsed, so a
+// lookup is two loads and no hashing -- it sits on the VM's call path.
+class ScopeTable {
+public:
+    // Null until set: buildScopes() fills in every node it walks, and a
+    // reader treats null as "no scope recorded", exactly as the old
+    // nullptr-initialised field did.
+    const Scope* get(const ASTNode& node) const {
+        const uint32_t tree = node.treeId();
+        if (tree >= trees_.size()) return nullptr;
+        const std::vector<Scope*>& slots = trees_[tree];
+        const uint32_t slot = node.slot();
+        return slot < slots.size() ? slots[slot] : nullptr;
+    }
+    Scope* get(const ASTNode& node) {
+        return const_cast<Scope*>(static_cast<const ScopeTable*>(this)->get(node));
+    }
+
+    void set(const ASTNode& node, Scope* scope) {
+        const uint32_t tree = node.treeId();
+        if (tree >= trees_.size()) trees_.resize(tree + 1);
+        std::vector<Scope*>& slots = trees_[tree];
+        const uint32_t slot = node.slot();
+        if (slot >= slots.size()) slots.resize(slot + 1, nullptr);
+        slots[slot] = scope;
+    }
+
+private:
+    // Indexed by treeId. Sparse in principle -- treeIds are handed out
+    // process-wide and a render only involves a few trees -- but the empty
+    // outer entries are 24 bytes each and never allocate, so the waste is
+    // a few tens of KB against a 55ms saving.
+    std::vector<std::vector<Scope*>> trees_;
+};
+
+} // namespace oscad

{openscad_cpp_evaluator-1.3.1 → openscad_cpp_evaluator-1.4.0}/external/openscad_cpp_parser/src/api.cpp

@@ -9,6 +9,10 @@
 #include <filesystem>
 #include <fstream>
 #include <set>
+#include <system_error>
+#include <cstdint>
+#include <unordered_map>
+#include <mutex>
 #include <sstream>
 
 namespace oscad {
@@ -86,6 +90,11 @@ std::string formatSyntaxError(const ParserDriver& driver, const std::string& cod
 } // namespace
 
 std::vector<std::unique_ptr<ASTNode>> parseAst(const std::string& code, const std::string& origin, SourceMap* sourceMap) {
+    // Stamps every node this parse builds with one treeId and a dense
+    // slot, so a ScopeTable can address it without the node carrying a
+    // Scope pointer of its own -- see ASTNode::slot().
+    ParseNumberingScope numbering;
+
     ParserDriver driver(origin);
     lexerBeginString(code);
     yy::parser parser(driver);
@@ -100,6 +109,9 @@ std::vector<std::unique_ptr<ASTNode>> parseAst(const std::string& code, const st
 
 std::vector<std::unique_ptr<ASTNode>> getASTFromString(const std::string& code, bool includeComments,
                                                         const std::string& origin) {
+    // Spans attachComments too: it builds CommentedExpr wrappers, and they
+    // belong to the same tree as what they wrap.
+    ParseNumberingScope numbering;
     auto ast = parseAst(code, origin); // propagates ParseError with the full diagnostic
     if (includeComments) {
         ast = attachComments(std::move(ast), code, origin);
@@ -121,6 +133,7 @@ std::string readFile(const std::string& path) {
 
 std::vector<std::unique_ptr<ASTNode>> parseSingleFile(const std::string& filePath, bool includeComments) {
     std::string code = readFile(filePath);
+    ParseNumberingScope numbering;   // spans attachComments -- see getASTFromString
     auto ast = parseAst(code, filePath);
     if (includeComments) {
         ast = attachComments(std::move(ast), code, filePath);
@@ -238,8 +251,115 @@ LibraryFileResult getASTFromLibraryFile(const std::string& currFile, const std::
     return LibraryFileResult{std::move(ast), *found};
 }
 
+
+
+namespace {
+
+using FileAst = std::vector<std::unique_ptr<ASTNode>>;
+using FileAstPtr = std::shared_ptr<const FileAst>;
+
+// One entry per (file, comments) -- keyed by PATH, with the content stamp
+// stored beside the tree rather than in the key. A stale stamp REPLACES the
+// entry instead of adding a second one: an editor re-renders on every save,
+// and a stamp-in-the-key cache would keep a full copy of every version the
+// file ever had.
+struct CacheKey {
+    std::string path;
+    bool comments;
+    bool operator==(const CacheKey& o) const { return comments == o.comments && path == o.path; }
+};
+struct CacheKeyHash {
+    size_t operator()(const CacheKey& k) const {
+        return std::hash<std::string>{}(k.path) ^ (k.comments ? 0x5bf03635U : 0U);
+    }
+};
+struct CacheEntry {
+    std::uintmax_t size = 0;
+    std::int64_t mtime = 0;
+    FileAstPtr ast;
+};
+
+std::mutex g_astCacheMutex;
+std::unordered_map<CacheKey, CacheEntry, CacheKeyHash> g_astCache;
+
+FileAstPtr parseFileShared(const std::string& absPath, bool includeComments) {
+    std::error_code ec;
+    const auto size = fs::file_size(absPath, ec);
+    const std::uintmax_t stampSize = ec ? 0 : size;
+    ec.clear();
+    const auto written = fs::last_write_time(absPath, ec);
+    const std::int64_t stampMtime = ec ? 0 : static_cast<std::int64_t>(written.time_since_epoch().count());
+
+    const CacheKey key{absPath, includeComments};
+    {
+        std::lock_guard<std::mutex> lock(g_astCacheMutex);
+        auto it = g_astCache.find(key);
+        if (it != g_astCache.end() && it->second.size == stampSize && it->second.mtime == stampMtime)
+            return it->second.ast;
+    }
+
+    // Parsed OUTSIDE the lock: parsing a library takes tens of
+    // milliseconds, and holding a global lock across it would serialise
+    // every thread. Two threads racing the same file both parse and one
+    // result is dropped -- wasteful once, never wrong, and far cheaper than
+    // the alternative.
+    auto parsed = std::make_shared<const FileAst>(parseSingleFile(absPath, includeComments));
+    std::lock_guard<std::mutex> lock(g_astCacheMutex);
+    CacheEntry& entry = g_astCache[key];
+    // Whoever writes last wins; the loser's tree stays alive in whatever
+    // ParsedProgram already borrowed it.
+    entry.size = stampSize;
+    entry.mtime = stampMtime;
+    entry.ast = parsed;
+    return parsed;
+}
+
+// Splices includes into a flat statement list of BORROWED nodes, collecting
+// what must stay alive. Mirrors resolveIncludes' walk exactly, including
+// the per-resolution `visited` set that makes a file contribute at most
+// once.
+void collectProgram(const FileAst& nodes, const std::string& currentFile, bool includeComments,
+                    std::set<std::string>& visited, ParsedProgram& out) {
+    for (const auto& node : nodes) {
+        if (node->kind() == NodeKind::IncludeStatement) {
+            const auto& inc = static_cast<const IncludeStatement&>(*node);
+            const std::string& filename = inc.filepath->val;
+            auto libFile = findLibraryFile(currentFile, filename);
+            if (!libFile) {
+                throw std::runtime_error("Included file '" + filename + "' not found. Searched relative to: " +
+                                          (currentFile.empty() ? "current directory" : currentFile));
+            }
+            std::string absLib = fs::absolute(*libFile).string();
+            if (!visited.insert(absLib).second) continue;
+            FileAstPtr included = parseFileShared(absLib, includeComments);
+            out.keepAlive.push_back(included);
+            collectProgram(*included, absLib, includeComments, visited, out);
+        } else {
+            out.nodes.push_back(node.get());
+        }
+    }
+}
+
+} // namespace
+
+ParsedProgram getProgramFromFile(const std::string& file, bool includeComments) {
+    const std::string abs = fs::absolute(file).string();
+    ParsedProgram out;
+    FileAstPtr own = parseFileShared(abs, includeComments);
+    out.keepAlive.push_back(own);
+    std::set<std::string> visited{abs};
+    collectProgram(*own, abs, includeComments, visited, out);
+    return out;
+}
+
 void clearAstCache() {
-    // No-op -- see the ponytail note on getASTFromFile() in api.hpp.
+    std::lock_guard<std::mutex> lock(g_astCacheMutex);
+    g_astCache.clear();
+}
+
+size_t astCacheSize() {
+    std::lock_guard<std::mutex> lock(g_astCacheMutex);
+    return g_astCache.size();
 }
 
 } // namespace oscad

openscad_cpp_evaluator-1.4.0/external/openscad_cpp_parser/src/scope.cpp

@@ -0,0 +1,75 @@
+#include "openscad_cpp_parser/api.hpp"
+
+#include <atomic>
+
+#include "openscad_cpp_parser/scope_table.hpp"
+
+#include "openscad_cpp_parser/ast/scope_builder.hpp"
+
+namespace oscad {
+
+std::unique_ptr<Scope> buildScopes(const std::vector<std::unique_ptr<ASTNode>>& ast) {
+    auto owned = std::make_unique<ScopeTable>();
+    ScopeTableScope recording(*owned);
+    auto root = std::make_unique<Scope>();
+    collectHoistedDeclarations(ast, *root);
+    for (auto& node : ast) {
+        node->buildScope(*root);
+    }
+    root->adoptTable(std::move(owned));
+    return root;
+}
+
+std::unique_ptr<Scope> buildScopes(const std::vector<ASTNode*>& ast) {
+    auto owned = std::make_unique<ScopeTable>();
+    ScopeTableScope recording(*owned);
+    auto root = std::make_unique<Scope>();
+    collectHoistedDeclarations(ast, *root);
+    for (ASTNode* node : ast) {
+        node->buildScope(*root);
+    }
+    root->adoptTable(std::move(owned));
+    return root;
+}
+
+
+namespace {
+// One per thread: a ParseNumberingScope installs a numbering for its
+// duration, so a node's constructor can stamp itself without every node
+// kind having to cooperate -- which matters because there is no generic
+// child walker to number a finished tree with.
+thread_local NodeNumbering* g_numbering = nullptr;
+thread_local ScopeTable* g_scopeTable = nullptr;
+std::atomic<uint32_t> g_nextTreeId{1};   // 0 is reserved for loose nodes
+std::atomic<uint32_t> g_nextLooseSlot{0};
+} // namespace
+
+NodeNumbering* currentNodeNumbering() { return g_numbering; }
+uint32_t nextLooseSlot() { return g_nextLooseSlot.fetch_add(1, std::memory_order_relaxed); }
+
+ParseNumberingScope::ParseNumberingScope()
+    : numbering_{g_nextTreeId.fetch_add(1, std::memory_order_relaxed), 0},
+      previous_(g_numbering),
+      installed_(g_numbering == nullptr) {
+    // Only the outermost scope installs: a nested one keeps the outer
+    // numbering so a parse plus its comment-attach pass stay one tree.
+    if (installed_) g_numbering = &numbering_;
+}
+
+ParseNumberingScope::~ParseNumberingScope() {
+    if (installed_) g_numbering = previous_;
+}
+
+ScopeTableScope::ScopeTableScope(ScopeTable& table) : previous_(g_scopeTable) { g_scopeTable = &table; }
+ScopeTableScope::~ScopeTableScope() { g_scopeTable = previous_; }
+
+void Scope::adoptTable(std::unique_ptr<ScopeTable> table) { ownedTable_ = std::move(table); }
+
+void ASTNode::setScope(Scope& s) {
+    // No table installed means nobody is recording scopes -- a parser-only
+    // caller walking a tree for its own reasons. Dropping the write keeps
+    // that a no-op rather than a crash.
+    if (g_scopeTable) g_scopeTable->set(*this, &s);
+}
+
+} // namespace oscad