From 6b701d0ad2cc6e378b48db2d2bda7aef8315f025 Mon Sep 17 00:00:00 2001 From: Sean Parent <160927019+sparent_adobe@users.noreply.github.com> Date: Fri, 13 Nov 2026 13:20:38 -0800 Subject: [PATCH 1/4] feat: port the f64 CEL standard library Register Rust-compatible numeric operations for the C++ parser and runtime, excluding powi and retaining structural sin_cos tuples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .clang-format | 121 ++++++++++ .gitattributes | 5 + .gitignore | 6 + CMakeLists.txt | 33 +++ CMakePresets.json | 106 +++++++++ cmake/CPM.cmake | 22 ++ docs/superpowers/plans/2026-11-13-f64-port.md | 84 +++++++ .../specs/2026-11-13-cel-std-design.md | 140 ++++++++++++ include/cel/std.hpp | 31 +++ src/std.cpp | 103 +++++++++ tests/std_test.cpp | 216 ++++++++++++++++++ 11 files changed, 867 insertions(+) create mode 100644 .clang-format create mode 100644 .gitattributes create mode 100644 .gitignore create mode 100644 CMakeLists.txt create mode 100644 CMakePresets.json create mode 100644 cmake/CPM.cmake create mode 100644 docs/superpowers/plans/2026-11-13-f64-port.md create mode 100644 docs/superpowers/specs/2026-11-13-cel-std-design.md create mode 100644 include/cel/std.hpp create mode 100644 src/std.cpp create mode 100644 tests/std_test.cpp diff --git a/.clang-format b/.clang-format new file mode 100644 index 0000000..2d80f91 --- /dev/null +++ b/.clang-format @@ -0,0 +1,121 @@ +# Auto-generated from cpp-library (https://github.com/stlab/cpp-library) +# Do not edit this file directly - it will be overwritten when templates are regenerated + +# Format style options described here: +# https://clang.llvm.org/docs/ClangFormatStyleOptions.html + +# Many of the alignment and single line changes were made to facilitate setting +# breakpoints on specific expressions. + +--- +AccessModifierOffset: -4 +AlignAfterOpenBracket: Align +AlignConsecutiveAssignments: false +AlignConsecutiveDeclarations: false +AlignEscapedNewlines: Left +AlignOperands: true +AlignTrailingComments: true +AllowAllParametersOfDeclarationOnNextLine: true +AllowShortBlocksOnASingleLine: false +AllowShortCaseLabelsOnASingleLine: false +AllowShortFunctionsOnASingleLine: All +AllowShortIfStatementsOnASingleLine: true +AllowShortLoopsOnASingleLine: false +# AlwaysBreakAfterDefinitionReturnType: TopLevel +AlwaysBreakAfterReturnType: None +AlwaysBreakBeforeMultilineStrings: false +AlwaysBreakTemplateDeclarations: true +BinPackArguments: true +BinPackParameters: false +# BraceWrapping: +# AfterClass: true +# AfterControlStatement: false +# AfterEnum: false +# AfterFunction: false +# AfterNamespace: false +# AfterObjCDeclaration: false +# AfterStruct: false +# AfterUnion: false +# AfterExternBlock: false +# BeforeCatch: false +# BeforeElse: false +# IndentBraces: false +# SplitEmptyFunction: true +# SplitEmptyRecord: true +# SplitEmptyNamespace: true +BreakBeforeBinaryOperators: None +BreakBeforeBraces: Attach +BreakBeforeInheritanceComma: false +BreakBeforeTernaryOperators: false +BreakConstructorInitializersBeforeComma: false +BreakConstructorInitializers: AfterColon +BreakAfterJavaFieldAnnotations: false +BreakStringLiterals: false +ColumnLimit: 100 +CommentPragmas: "^ IWYU pragma:" +CompactNamespaces: false +ConstructorInitializerAllOnOneLineOrOnePerLine: false +ConstructorInitializerIndentWidth: 4 +ContinuationIndentWidth: 4 +Cpp11BracedListStyle: true +DerivePointerAlignment: false +DisableFormat: false +ExperimentalAutoDetectBinPacking: false +FixNamespaceComments: true +ForEachMacros: + - foreach + - Q_FOREACH + - BOOST_FOREACH +IncludeBlocks: Preserve +IncludeCategories: + - Regex: '^"(llvm|llvm-c|clang|clang-c)/' + Priority: 2 + - Regex: '^(<|"(gtest|gmock|isl|json)/)' + Priority: 3 + - Regex: ".*" + Priority: 1 +IncludeIsMainRegex: "$" +IndentCaseLabels: true +IndentPPDirectives: None # Other option is AfterHash, which indents top level includes as well +IndentWidth: 4 +IndentWrappedFunctionNames: true +JavaScriptQuotes: Leave +JavaScriptWrapImports: true +KeepEmptyLinesAtTheStartOfBlocks: false +MacroBlockBegin: "" +MacroBlockEnd: "" +MaxEmptyLinesToKeep: 1 +NamespaceIndentation: None +ObjCBlockIndentWidth: 4 +ObjCSpaceAfterProperty: true +ObjCSpaceBeforeProtocolList: true +PenaltyBreakAssignment: 2 +PenaltyBreakBeforeFirstCallParameter: 19 +PenaltyBreakComment: 300 +PenaltyBreakFirstLessLess: 120 +PenaltyBreakString: 1000 +PenaltyExcessCharacter: 1000000 +PenaltyReturnTypeOnItsOwnLine: 1000 +PointerAlignment: Left +ReflowComments: true +SortIncludes: true +SortUsingDeclarations: true +SpaceAfterCStyleCast: false +SpaceAfterTemplateKeyword: true +SpaceBeforeAssignmentOperators: true +SpaceBeforeParens: ControlStatements +SpaceInEmptyParentheses: false +SpacesBeforeTrailingComments: 1 +SpacesInAngles: false +SpacesInContainerLiterals: true +SpacesInCStyleCastParentheses: false +SpacesInParentheses: false +SpacesInSquareBrackets: false +Standard: c++17 +TabWidth: 4 +UseTab: Never +--- +Language: Cpp +--- +Language: ObjC +PointerAlignment: Right diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 0000000..aeaac85 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,5 @@ +# Auto-generated from cpp-library (https://github.com/stlab/cpp-library) +# Do not edit this file directly - it will be overwritten when templates are regenerated + +# Auto detect text files and perform LF normalization +* text=auto diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a31b5d6 --- /dev/null +++ b/.gitignore @@ -0,0 +1,6 @@ +/build*/ +/.claude/worktrees/ +/.superpowers/ +/.cache/ +/.clangd +/compile_commands.json diff --git a/CMakeLists.txt b/CMakeLists.txt new file mode 100644 index 0000000..0e7df79 --- /dev/null +++ b/CMakeLists.txt @@ -0,0 +1,33 @@ +cmake_minimum_required(VERSION 3.24) + +include(cmake/CPM.cmake) +CPMAddPackage("gh:stlab/cpp-library@5.8.1") +include("${cpp-library_SOURCE_DIR}/cpp-library.cmake") +cpp_library_enable_dependency_tracking() + +project(std LANGUAGES CXX) +set(CMAKE_CXX_EXTENSIONS OFF) +if(PROJECT_IS_TOP_LEVEL) + include(CTest) +endif() + +option(CEL_INSTALL "Enable installation for CEL libraries" ${PROJECT_IS_TOP_LEVEL}) +CPMAddPackage( + NAME cel-parser + GITHUB_REPOSITORY stlab/cel-parser + GIT_TAG fac94057fd8a26a06ababbd453b86050584a3c61 +) + +if(NOT CPP_LIBRARY_VERSION) + set(CPP_LIBRARY_VERSION "0.1.0") +endif() +cpp_library_setup( + DESCRIPTION "The f64 CEL standard library" + NAMESPACE cel + REQUIRES_CPP_VERSION 20 + HEADERS std.hpp + SOURCES std.cpp + TESTS std_test.cpp +) +cpp_library_map_dependency("cel::parser" "cel-parser CONFIG") +target_link_libraries(std PUBLIC cel::parser) diff --git a/CMakePresets.json b/CMakePresets.json new file mode 100644 index 0000000..99ba84a --- /dev/null +++ b/CMakePresets.json @@ -0,0 +1,106 @@ +{ + "version": 2, + "configurePresets": [ + { + "name": "default", + "displayName": "Default Configuration", + "description": "Default configuration for building the library", + "binaryDir": "${sourceDir}/build/default", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Release", + "BUILD_TESTING": "OFF", + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_CXX_EXTENSIONS": "OFF", + "CPM_SOURCE_CACHE": "${sourceDir}/.cache/cpm" + } + }, + { + "name": "test", + "displayName": "Test Configuration", + "description": "Configuration for building and running tests", + "binaryDir": "${sourceDir}/build/test", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "BUILD_TESTING": "ON", + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_CXX_EXTENSIONS": "OFF", + "CPM_SOURCE_CACHE": "${sourceDir}/.cache/cpm" + } + }, + { + "name": "docs", + "displayName": "Documentation Configuration", + "description": "Configuration for building documentation", + "binaryDir": "${sourceDir}/build/docs", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Release", + "BUILD_TESTING": "OFF", + "BUILD_DOCS": "ON", + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_CXX_EXTENSIONS": "OFF", + "CPM_SOURCE_CACHE": "${sourceDir}/.cache/cpm" + } + }, + { + "name": "clang-tidy", + "displayName": "Clang-Tidy Configuration", + "description": "Configuration for running clang-tidy static analysis", + "binaryDir": "${sourceDir}/build/clang-tidy", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Debug", + "BUILD_TESTING": "ON", + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_CXX_EXTENSIONS": "OFF", + "CMAKE_CXX_CLANG_TIDY": "clang-tidy", + "CPM_SOURCE_CACHE": "${sourceDir}/.cache/cpm" + } + }, + { + "name": "init", + "displayName": "Initialize Templates", + "description": "Force regeneration of template files (CMakePresets.json, CI, etc.)", + "binaryDir": "${sourceDir}/build/init", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Release", + "BUILD_TESTING": "OFF", + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_CXX_EXTENSIONS": "OFF", + "CPP_LIBRARY_FORCE_INIT": "ON", + "CPM_SOURCE_CACHE": "${sourceDir}/.cache/cpm" + } + }, + { + "name": "install", + "displayName": "Install Configuration", + "description": "Release build for installation with CPM_USE_LOCAL_PACKAGES enabled for testing installed packages", + "binaryDir": "${sourceDir}/build/install", + "generator": "Ninja", + "cacheVariables": { + "CMAKE_BUILD_TYPE": "Release", + "BUILD_TESTING": "OFF", + "CMAKE_EXPORT_COMPILE_COMMANDS": "ON", + "CMAKE_CXX_EXTENSIONS": "OFF", + "CPM_USE_LOCAL_PACKAGES": "ON", + "CPM_SOURCE_CACHE": "${sourceDir}/.cache/cpm" + } + } + ], + "buildPresets": [ + { "name": "default", "displayName": "Default Build", "configurePreset": "default" }, + { "name": "test", "displayName": "Build Tests", "configurePreset": "test" }, + { "name": "docs", "displayName": "Build Docs", "configurePreset": "docs", "targets": "docs" }, + { "name": "clang-tidy", "displayName": "Build with Clang-Tidy", "configurePreset": "clang-tidy" }, + { "name": "init", "displayName": "Initialize Templates", "configurePreset": "init" }, + { "name": "install", "displayName": "Build for Installation", "configurePreset": "install" } + ], + "testPresets": [ + { "name": "test", "displayName": "Run All Tests", "configurePreset": "test", "output": { "outputOnFailure": true } }, + { "name": "clang-tidy", "displayName": "Run Tests with Clang-Tidy", "configurePreset": "clang-tidy", "output": { "outputOnFailure": true } }, + { "name": "init", "displayName": "Initialize Templates", "configurePreset": "init", "output": { "outputOnFailure": true } } + ] +} diff --git a/cmake/CPM.cmake b/cmake/CPM.cmake new file mode 100644 index 0000000..938fbf0 --- /dev/null +++ b/cmake/CPM.cmake @@ -0,0 +1,22 @@ +# SPDX-License-Identifier: MIT +# SPDX-FileCopyrightText: Copyright (c) 2019-2023 Lars Melchior and contributors +set(CPM_DOWNLOAD_VERSION 0.43.2) +set(CPM_HASH_SUM "49a3bef91ceb65bb66d57255e12d1ffd22abc2f6408fa9fe4534c544a2f232aa") + +if(CPM_PATH) + set(CPM_DOWNLOAD_LOCATION "${CPM_PATH}/CPM.cmake") +elseif(DEFINED ENV{CPM_PATH}) + set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_PATH}/CPM.cmake") +elseif(CPM_SOURCE_CACHE) + set(CPM_DOWNLOAD_LOCATION "${CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake") +elseif(DEFINED ENV{CPM_SOURCE_CACHE}) + set(CPM_DOWNLOAD_LOCATION "$ENV{CPM_SOURCE_CACHE}/cpm/CPM_${CPM_DOWNLOAD_VERSION}.cmake") +else() + set(CPM_DOWNLOAD_LOCATION "${CMAKE_BINARY_DIR}/cmake/CPM_${CPM_DOWNLOAD_VERSION}.cmake") +endif() +get_filename_component(CPM_DOWNLOAD_LOCATION "${CPM_DOWNLOAD_LOCATION}" ABSOLUTE) +file(DOWNLOAD + "https://github.com/cpm-cmake/CPM.cmake/releases/download/v${CPM_DOWNLOAD_VERSION}/CPM.cmake" + "${CPM_DOWNLOAD_LOCATION}" EXPECTED_HASH "SHA256=${CPM_HASH_SUM}" + TLS_VERIFY ON) +include("${CPM_DOWNLOAD_LOCATION}") diff --git a/docs/superpowers/plans/2026-11-13-f64-port.md b/docs/superpowers/plans/2026-11-13-f64-port.md new file mode 100644 index 0000000..2fd289a --- /dev/null +++ b/docs/superpowers/plans/2026-11-13-f64-port.md @@ -0,0 +1,84 @@ +# CEL f64 standard library implementation plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development +> (recommended) or superpowers:executing-plans to implement this plan task-by-task. +> Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Build the public C++ f64 CEL standard library, excluding powi. + +**Architecture:** A compiled installer registers exact numeric signatures in +cel-parser. Private standard-library adapters preserve Rust numeric semantics; +cel-runtime owns and executes the emitted operations. + +**Tech stack:** C++20, CMake, cpp-library, CPM, doctest, Doxygen. + +**Spec:** `docs/superpowers/specs/2026-11-13-cel-std-design.md` + +## Global constraints + +- Repository: public `stlab/cel-std`; GitHub account: `sean-parent`. +- Use C++20, cpp-library, and CPM with verified pinned dependencies. +- Expose ``, `cel::std`, and `void cel::stdlib::install(cel::op_lookup&)`. +- Retain only f64 signatures; exclude powi; retain structural sin_cos tuples. +- Preserve operation names, operand order, errors, and Rust floating-point semantics. +- Work on `feat/f64-port` in `.claude/worktrees/f64-port`, never directly on main. +- Every introduced type and function has an adjacent contract and unit coverage. + +## Review focus + +- Ambient rounding modes must not change ties-to-even results: test all four modes. +- Clamp must reject NaN bounds without invoking a C++ library precondition violation. +- Negative zero must retain operation-specific signs: assert signbit and infinities. +- Installed consumers must resolve parser/runtime without local source-tree paths. +- Programs must retain usable callbacks after parser and lookup destruction. + +## File structure + +- `CMakeLists.txt`, `cmake/CPM.cmake`: library, pinned dependencies, tests, docs. +- `include/cel/std.hpp`: public installation contract and shared example. +- `src/std.cpp`: persistent registrations and numeric adapters. +- `tests/std_test.cpp`: contract-derived numeric and parser integration tests. +- `tests/consumer/`, `tests/consumer.cmake.in`: independent package/source consumers. +- `examples/example.cpp`: runnable tutorial example. +- `README.md`, `docs/tutorial.md`, `docs/reference.dox`: orientation, tutorial, reference. +- `.github/workflows/ci.yml`, `.gitignore`, `LICENSE`, formatting configuration: + repository conventions and repeatable checks. + +### Task 1: Numeric installation and execution + +**Consumes:** Parser registration APIs and runtime native tuple adapters. +**Produces:** `void cel::stdlib::install(cel::op_lookup&)`, target `cel::std`. + +- [ ] Inspect the exact parser registration API and cpp-library setup before scaffolding. +- [ ] Write `std_test.cpp`: ordinary/receiver calls for every listed operation, + assert `atan2(1.0, -1.0)` is approximately 3*pi/4, `log(8.0, 2.0)` is + approximately 3, and `sin_cos(0.0)` is the tuple `(0.0, 1.0)`. +- [ ] Configure the project and run the test build; confirm the installer is absent. +- [ ] Implement the public header and installer with private, contracted adapters. +- [ ] Add and run edge tests: `signum(-0.0) == -1.0`, NaN min/max operands, + invalid clamp bounds, signed zeros, infinities, exact FMA cancellation, + `rem_euclid(-7.0, 4.0) == 1.0`, `fract(-1.25) == -0.25`, + and ties-to-even in FE_TONEAREST/FE_DOWNWARD/FE_UPWARD/FE_TOWARDZERO. +- [ ] Add integration tests for closures, unrelated registrations, parser lifetime, + tuple projection, and rejection of powi, wrong types, and wrong arities. +- [ ] Run `cmake --build build` and `ctest --test-dir build --output-on-failure`; + require all tests to pass, then commit the coherent implementation. + +### Task 2: Consumer packaging and user documentation + +**Consumes:** Task 1's installer and target. +**Produces:** Verified source/installed consumers, tutorial, reference, CI. + +- [ ] Write a minimal independent consumer calling install, parsing + `sqrt(9.0)`, and asserting a prepared execution result of 3.0. +- [ ] Exercise the source and installed forms before adding missing export mappings; + resolve package discovery with cpp-library's dependency mapping facilities. +- [ ] Verify the published CEL book URL and operation anchors. +- [ ] Write and compile the tutorial example; use it in the Doxygen tutorial. +- [ ] Write installer/package reference and an exact f64 signature table linking + each operation to its language-book entry; explicitly exclude powi and other types. +- [ ] Add CI using verified build/test/documentation commands, not assumed targets. +- [ ] Run all unit and consumer tests, format checks, Doxygen warnings checks, + and an available sanitizer configuration. Fix in-scope review findings. +- [ ] Commit the documentation and packaging, push the feature branch, and report + the repository, branch, worktree, check results, and any material limitations. diff --git a/docs/superpowers/specs/2026-11-13-cel-std-design.md b/docs/superpowers/specs/2026-11-13-cel-std-design.md new file mode 100644 index 0000000..2764ee0 --- /dev/null +++ b/docs/superpowers/specs/2026-11-13-cel-std-design.md @@ -0,0 +1,140 @@ +# C++ CEL standard library + +Date: 2026-11-13 +Status: Approved + +## Intent + +Create the public `stlab/cel-std` repository as a C++ port of the floating-point +subset of Rust `cel-std`. C++ applications install the library into the existing +`stlab/cel-parser` lookup and execute expressions through `stlab/cel-runtime`. + +The user selected a public repository and explicitly excluded `powi` while +retaining `sin_cos`. + +## Goals and boundaries + +Preserve Rust CEL operation names, operand order, arities, result types, and +documented numeric behavior for f64 operations. Map f64 to C++ `double`. +Register no f32 or integer overloads. Do not modify the runtime or parser ports, +extend CEL syntax, add implicit conversions, or provide a parallel math API. + +The supported operations are: + +```text +min max clamp abs signum sqrt floor ceil trunc fract round_ties_even round +sin cos tan asin acos atan atan2 sin_cos to_radians to_degrees hypot cbrt +powf exp exp2 ln log log2 log10 recip mul_add rem_euclid copysign +``` + +All operands and scalar results are f64. `sin_cos(f64)` returns the structural +CEL tuple `(f64, f64)`, ordered sine then cosine. `powi` is not registered. +Ordinary calls and receiver calls resolve to the same signatures. Persistent +registrations remain available in closure bodies. + +## Approaches + +A compiled installer library matches the existing parser package, keeps +implementation details private, and gives consumers a small public interface. +This is the recommended approach. + +A header-only implementation removes one compiled artifact but exposes numeric +adapters and registration machinery in downstream translation units. It offers +no integration benefit for this port. + +A standalone math library with a separate parser adapter adds an API and +packaging boundary that the requested CEL port does not need. + +## Public interface and ownership + +Provide ``, the CMake target `cel::std`, and +`cel::stdlib::install(cel::op_lookup&)`. Use `stdlib`, rather than the earlier +suggested `cel::std`, to avoid shadowing the C++ standard namespace inside `cel`. +These spellings are proposed builder choices, not existing upstream APIs. + +The installer adds complete named operation signatures through the parser's +public registration APIs. It retains no references to the caller's lookup. +Emitted numeric callbacks own no mutable shared state. Programs use the existing +runtime ownership and prepared-call interfaces. + +As in Rust, the installer requires that none of its exact signatures is already +installed. Disjoint overloads and unrelated user registrations remain valid. +Do not add transactional copies or promise rollback after registration failure. +Document installation complexity against the actual parser registration costs. + +## Numeric behavior and failures + +Use C++20 standard-library facilities wherever they satisfy the Rust contract: +for example, `` functions, `std::fma`, and angle-conversion constants. +Keep small private adapters for semantic differences. + +In particular, preserve NaN handling in min/max and signum, signed-zero behavior +where specified, ties-to-even rounding independent of the ambient rounding mode, +the Rust definition of fract and rem_euclid, and argument order for atan2, +log, copysign, and mul_add. Do not replace rem_euclid with std::remainder. + +Clamp rejects reversed or NaN bounds at evaluation time with the message +`invalid clamp bounds`; NaN input with valid bounds follows Rust behavior. +Other floating-point domain errors produce floating-point results, including +NaN and infinity, rather than new evaluation exceptions. NaN payloads and +bit-identical transcendental results are not promised by the Rust book. +Use tolerance comparisons for approximate results. + +## Build, dependencies, and repository + +Use C++20, `stlab/cpp-library`, and CPM in the pattern established by the parser +port. Pin dependencies to verified revisions. Depend publicly on `cel::parser`, +which supplies the runtime dependency; avoid fetching a second runtime version. +Follow the ports' shared `CEL_INSTALL` convention before adding dependencies. + +Support both CPM source consumption and an installed CMake package, including +transitive dependency discovery. Use the existing ports' license conventions +after verifying their license files. Include build/test CI and Doxygen +documentation generation using cpp-library's supported mechanisms. + +Create the new repository beside the existing ports and implement on a branch +in a worktree under its `.claude/worktrees/`. Do not modify cel-rs or commit +implementation directly to main. + +## Documentation + +The README orients C++ consumers and links to the tutorial and API reference. +The Doxygen tutorial shows dependency setup, installation, parsing, execution, +receiver calls, and tuple extraction with compiled examples. + +The reference documents the installer, package, subset boundary, and signatures. +Each retained operation links to its corresponding section in the published +CEL language book instead of duplicating operation prose. Verify the published +base URL and anchors before using them. Clearly state that the linked Rust book +also describes types and powi that this C++ subset does not support. + +## Validation and acceptance + +Use the ports' existing test framework and cpp-library checks. Test every +operation through parsed CEL, including both call forms and operand order. +Cover closure visibility, tuple typing and extraction, unrelated registrations, +and absence of powi and unsupported overloads. + +Add focused numeric edge cases for NaN, infinity, signed zeros, halfway values, +nondefault rounding modes, invalid clamp bounds, Euclidean remainders, and fused +multiply-add. Derive expected results from the Rust/public book contracts. +Exercise programs after their parser is destroyed. + +Build and run examples and documentation snippets. Generate Doxygen without +unresolved internal references. Verify an independent source consumer and an +installed-package consumer. Run available compiler, formatter, and sanitizer +checks appropriate to the new C++ library, and report any unavailable checks. + +## Builder decisions + +Choose internal adapter organization and registration helpers after examining +the exact current parser API. Verify cpp-library's current supported setup, +formatting, CI, packaging, and documentation commands rather than inventing +targets. Resolve standard-library semantic differences with the smallest +contracted, unit-tested adapters. + +Use the `sean-parent` GitHub account for the new repository, as explicitly +requested by the user. Switch the active GitHub CLI account with `gh auth switch` +and select that username in the new repository's local Git credential settings. +Verify permission to create `stlab/cel-std`. If creation is denied, retain +the local repository and report the remote-creation blocker. diff --git a/include/cel/std.hpp b/include/cel/std.hpp new file mode 100644 index 0000000..ed0ced4 --- /dev/null +++ b/include/cel/std.hpp @@ -0,0 +1,31 @@ +// SPDX-License-Identifier: BSL-1.0 +#ifndef CEL_STD_HPP +#define CEL_STD_HPP + +namespace cel { +class op_lookup; + +/// Installs the f64 CEL standard library into an operation lookup. +namespace stdlib { +/// Registers the Rust cel-std f64 signatures, excluding powi. +/// +/// Ordinary and receiver calls share these persistent registrations, including +/// inside closure bodies. sin_cos returns a structural (f64, f64) tuple. +/// The lookup owns all registration state; emitted programs retain their callbacks. +/// +/// \pre None of these exact signatures is already registered. +/// +/// Registration failures propagate; installation need not leave the lookup unchanged. +/// Numeric evaluation follows the linked CEL operation contracts. clamp throws +/// std::invalid_argument("invalid clamp bounds") for reversed or NaN bounds. +/// +/// Expected complexity: O(s + 1) time for s existing signatures under the installed +/// names, with constant additional library registration storage. +/// +/// \see \ref tutorial for a complete installation and execution example. +/// \see \ref reference for the supported signatures and language-book links. +void install(op_lookup& lookup); +} // namespace stdlib +} // namespace cel + +#endif diff --git a/src/std.cpp b/src/std.cpp new file mode 100644 index 0000000..2852a35 --- /dev/null +++ b/src/std.cpp @@ -0,0 +1,103 @@ +// SPDX-License-Identifier: BSL-1.0 +#include +#include +#include +#include +#include +#include +#include +#include +#include +#include + +namespace { +static_assert(std::numeric_limits::is_iec559 && std::numeric_limits::digits == 53 && + std::numeric_limits::max_exponent == 1024, + "CEL f64 requires IEEE 754 binary64 double"); + +/// Identifies one ordinary function without mutable callback state. +template +struct function_marker {}; + +/// Registers one exact signature for direct, receiver, and ordinary calls. +/// +/// \pre No registration duplicates the installed operand signatures. +/// Expected complexity: O(s + 1) time for s existing overloads of these names; +/// constant additional registration storage. +template +void add(cel::op_lookup& lookup, std::string_view name) { + using result = std::invoke_result_t; + using marker = function_marker; + lookup.register_op(name, Function); + lookup.register_function(name, marker{}); + lookup.register_op( + "()", [](marker, A... arguments) { return Function(arguments...); }); +} + +/// Rounds to the nearest integer, selecting the even neighbor on a tie. +/// +/// Preserves signed zeros and nonfinite values independently of the rounding mode. +double round_ties_even(double x) { + if (!std::isfinite(x)) return x; + return std::copysign(x - std::remainder(x, 1.0), x); +} + +/// Returns Rust's Euclidean remainder, including a possible rounded divisor magnitude. +double rem_euclid(double x, double divisor) { + const auto remainder = std::fmod(x, divisor); + return remainder < 0.0 ? remainder + std::abs(divisor) : remainder; +} + +/// Returns x bounded by ordered limits, preserving NaN x. +/// +/// Throws std::invalid_argument("invalid clamp bounds") for reversed or NaN bounds. +double clamp(double x, double lower, double upper) { + if (!(lower <= upper)) throw std::invalid_argument("invalid clamp bounds"); + return std::clamp(x, lower, upper); +} +} // namespace + +namespace cel::stdlib { +void install(op_lookup& lookup) { + add<[](double a, double b) { return std::fmin(a, b); }, double, double>(lookup, "min"); + add<[](double a, double b) { return std::fmax(a, b); }, double, double>(lookup, "max"); + add(lookup, "clamp"); + add<[](double x) { return std::abs(x); }, double>(lookup, "abs"); + add<[](double x) { return std::isnan(x) ? x : std::copysign(1.0, x); }, double>(lookup, + "signum"); + add<[](double x) { return std::sqrt(x); }, double>(lookup, "sqrt"); + add<[](double x) { return std::floor(x); }, double>(lookup, "floor"); + add<[](double x) { return std::ceil(x); }, double>(lookup, "ceil"); + add<[](double x) { return std::trunc(x); }, double>(lookup, "trunc"); + add<[](double x) { return x - std::trunc(x); }, double>(lookup, "fract"); + add(lookup, "round_ties_even"); + add<[](double x) { return std::round(x); }, double>(lookup, "round"); + add<[](double x) { return std::sin(x); }, double>(lookup, "sin"); + add<[](double x) { return std::cos(x); }, double>(lookup, "cos"); + add<[](double x) { return std::tan(x); }, double>(lookup, "tan"); + add<[](double x) { return std::asin(x); }, double>(lookup, "asin"); + add<[](double x) { return std::acos(x); }, double>(lookup, "acos"); + add<[](double x) { return std::atan(x); }, double>(lookup, "atan"); + add<[](double y, double x) { return std::atan2(y, x); }, double, double>(lookup, "atan2"); + add<[](double x) { return std::tuple{std::sin(x), std::cos(x)}; }, double>(lookup, "sin_cos"); + add<[](double x) { return x * (std::numbers::pi / 180.0); }, double>(lookup, "to_radians"); + add<[](double x) { return x * (180.0 / std::numbers::pi); }, double>(lookup, "to_degrees"); + add<[](double x, double y) { return std::hypot(x, y); }, double, double>(lookup, "hypot"); + add<[](double x) { return std::cbrt(x); }, double>(lookup, "cbrt"); + add<[](double x, double exponent) { return std::pow(x, exponent); }, double, double>(lookup, + "powf"); + add<[](double x) { return std::exp(x); }, double>(lookup, "exp"); + add<[](double x) { return std::exp2(x); }, double>(lookup, "exp2"); + add<[](double x) { return std::log(x); }, double>(lookup, "ln"); + add<[](double x, double base) { return std::log(x) / std::log(base); }, double, double>(lookup, + "log"); + add<[](double x) { return std::log2(x); }, double>(lookup, "log2"); + add<[](double x) { return std::log10(x); }, double>(lookup, "log10"); + add<[](double x) { return 1.0 / x; }, double>(lookup, "recip"); + add<[](double x, double multiplier, double addend) { return std::fma(x, multiplier, addend); }, + double, double, double>(lookup, "mul_add"); + add(lookup, "rem_euclid"); + add<[](double magnitude, double sign) { return std::copysign(magnitude, sign); }, double, + double>(lookup, "copysign"); +} +} // namespace cel::stdlib diff --git a/tests/std_test.cpp b/tests/std_test.cpp new file mode 100644 index 0000000..d495bcb --- /dev/null +++ b/tests/std_test.cpp @@ -0,0 +1,216 @@ +// SPDX-License-Identifier: BSL-1.0 +#include +#include +#include +#include +#include +#include +#include +#include +#include +#define DOCTEST_CONFIG_IMPLEMENT_WITH_MAIN +#include + +namespace { +/// Compiles an installed-library expression and executes it after destroying its parser. +/// +/// Complexity: O(compilation plus program execution) time and program storage. +template +R evaluate(std::string_view text) { + auto program = [&] { + cel::op_lookup lookup; + cel::stdlib::install(lookup); + cel::parser parser(std::move(lookup)); + return parser.parse_str(text); + }(); + cel::raw_stack stack; + return program.template prepare().call(stack); +} + +/// Specifies one ordinary and receiver call with its independently derived result. +struct call_case { + const char* ordinary; ///< CEL ordinary call. + const char* receiver; ///< Equivalent CEL receiver call. + double expected; ///< Expected result, within transcendental precision. +}; +} // namespace + +TEST_CASE("each scalar operation preserves its name signature and argument order") { + const call_case cases[]{ + {"min(3.0, -5.0)", "3.0.min(-5.0)", -5.0}, + {"max(3.0, -5.0)", "3.0.max(-5.0)", 3.0}, + {"clamp(7.0, 1.0, 4.0)", "7.0.clamp(1.0, 4.0)", 4.0}, + {"abs(-3.0)", "(-3.0).abs()", 3.0}, + {"signum(-3.0)", "(-3.0).signum()", -1.0}, + {"sqrt(9.0)", "9.0.sqrt()", 3.0}, + {"floor(-1.25)", "(-1.25).floor()", -2.0}, + {"ceil(-1.25)", "(-1.25).ceil()", -1.0}, + {"trunc(-1.25)", "(-1.25).trunc()", -1.0}, + {"fract(-1.25)", "(-1.25).fract()", -0.25}, + {"round_ties_even(2.5)", "2.5.round_ties_even()", 2.0}, + {"round(-2.5)", "(-2.5).round()", -3.0}, + {"sin(0.5)", "0.5.sin()", 0.479425538604203}, + {"cos(0.5)", "0.5.cos()", 0.8775825618903728}, + {"tan(0.5)", "0.5.tan()", 0.5463024898437905}, + {"asin(0.5)", "0.5.asin()", 0.5235987755982989}, + {"acos(0.5)", "0.5.acos()", 1.0471975511965979}, + {"atan(1.0)", "1.0.atan()", 0.7853981633974483}, + {"atan2(1.0, -1.0)", "1.0.atan2(-1.0)", 2.356194490192345}, + {"to_radians(180.0)", "180.0.to_radians()", 3.141592653589793}, + {"to_degrees(0.5)", "0.5.to_degrees()", 28.64788975654116}, + {"hypot(3.0, 4.0)", "3.0.hypot(4.0)", 5.0}, + {"cbrt(-8.0)", "(-8.0).cbrt()", -2.0}, + {"powf(9.0, 0.5)", "9.0.powf(0.5)", 3.0}, + {"exp(1.0)", "1.0.exp()", 2.718281828459045}, + {"exp2(3.0)", "3.0.exp2()", 8.0}, + {"ln(2.0)", "2.0.ln()", 0.6931471805599453}, + {"log(8.0, 2.0)", "8.0.log(2.0)", 3.0}, + {"log2(8.0)", "8.0.log2()", 3.0}, + {"log10(100.0)", "100.0.log10()", 2.0}, + {"recip(4.0)", "4.0.recip()", 0.25}, + {"mul_add(2.0, 3.0, 4.0)", "2.0.mul_add(3.0, 4.0)", 10.0}, + {"rem_euclid(-7.0, 4.0)", "(-7.0).rem_euclid(4.0)", 1.0}, + {"copysign(2.0, -3.0)", "2.0.copysign(-3.0)", -2.0}, + }; + // Exercise every signature through both source call forms. + for (const auto& test : cases) { + CAPTURE(test.ordinary); + CHECK(evaluate(test.ordinary) == doctest::Approx(test.expected).epsilon(1e-12)); + CHECK(evaluate(test.receiver) == doctest::Approx(test.expected).epsilon(1e-12)); + } +} + +TEST_CASE("sin_cos returns a structural sine then cosine tuple") { + const auto ordinary = evaluate>("sin_cos(0.0)"); + const auto receiver = evaluate>("0.0.sin_cos()"); + CHECK(ordinary == std::tuple{0.0, 1.0}); + CHECK(receiver == ordinary); + CHECK(evaluate("sin_cos(0.0).1") == 1.0); + const auto nonzero = evaluate>("sin_cos(0.5)"); + CHECK(std::get<0>(nonzero) == doctest::Approx(0.479425538604203)); + CHECK(std::get<1>(nonzero) == doctest::Approx(0.8775825618903728)); +} + +TEST_CASE("persistent library operations are visible in closure bodies") { + CHECK(evaluate("(|| sqrt(9.0))()") == 3.0); + CHECK(evaluate("(|x: f64| x.clamp(0.0, 4.0))(9.0)") == 4.0); +} + +TEST_CASE("installation preserves unrelated registrations and disjoint overloads") { + cel::op_lookup lookup; + lookup.register_op("twice", [](double x) { return x * 2.0; }); + lookup.register_op("min", [](bool a, bool b) { return a && b; }); + cel::stdlib::install(lookup); + cel::parser parser(std::move(lookup)); + cel::raw_stack stack; + CHECK(parser.parse_str("3.0.twice()").prepare().call(stack) == 6.0); + CHECK_FALSE(parser.parse_str("true.min(false)").prepare().call(stack)); + CHECK(parser.parse_str("min(2.0, 3.0)").prepare().call(stack) == 2.0); +} + +TEST_CASE("the subset rejects powi unsupported operand types and wrong arities") { + cel::op_lookup lookup; + cel::stdlib::install(lookup); + cel::parser parser(std::move(lookup)); + for (auto text : {"powi(2.0, 3.0)", "2.0.powi(3.0)", "sqrt(true)", "min(true, false)", + "sqrt(1.0, 2.0)", "clamp(1.0, 2.0)", "sin_cos()", "sqrt(1.0f32)"}) { + CAPTURE(text); + CHECK_THROWS_AS(parser.parse_str(text), cel::parse_error); + } + CHECK(evaluate("sqrt(4.0)") == 2.0); +} + +TEST_CASE("clamp validates bounds and otherwise preserves Rust floating behavior") { + for (auto text : + {"clamp(1.0, 3.0, 2.0)", "clamp(1.0, 0.0 / 0.0, 2.0)", "clamp(1.0, 0.0, 0.0 / 0.0)"}) { + CAPTURE(text); + CHECK_THROWS_WITH_AS(evaluate(text), "invalid clamp bounds", std::invalid_argument); + } + CHECK(std::isnan(evaluate("clamp(0.0 / 0.0, 0.0, 1.0)"))); + CHECK(evaluate("clamp(-1e9999, -2.0, 2.0)") == -2.0); + CHECK(evaluate("clamp(1e9999, -2.0, 2.0)") == 2.0); + CHECK(evaluate("clamp(4.0, 2.0, 2.0)") == 2.0); + CHECK(std::signbit(evaluate("clamp(-0.0, 0.0, 1.0)"))); +} + +TEST_CASE("extrema ignore a lone NaN and preserve infinities") { + for (auto name : {"min", "max"}) { + const std::string prefix = std::string(name) + "("; + CHECK(evaluate(prefix + "0.0 / 0.0, 4.0)") == 4.0); + CHECK(evaluate(prefix + "4.0, 0.0 / 0.0)") == 4.0); + CHECK(std::isnan(evaluate(prefix + "0.0 / 0.0, 0.0 / 0.0)"))); + } + CHECK(evaluate("min(-1e9999, 2.0)") == -std::numeric_limits::infinity()); + CHECK(evaluate("max(1e9999, 2.0)") == std::numeric_limits::infinity()); +} + +TEST_CASE("signum distinguishes signed zeros and propagates NaN") { + CHECK(evaluate("signum(-0.0)") == -1.0); + CHECK(evaluate("signum(0.0)") == 1.0); + CHECK(evaluate("signum(-1e9999)") == -1.0); + CHECK(evaluate("signum(1e9999)") == 1.0); + CHECK(std::isnan(evaluate("signum(0.0 / 0.0)"))); + CHECK_FALSE(std::signbit(evaluate("abs(-0.0)"))); +} + +TEST_CASE("floating domain failures produce NaN and infinity rather than exceptions") { + for (auto text : + {"sqrt(-1.0)", "asin(2.0)", "acos(-2.0)", "sin(1e9999)", "cos(1e9999)", "tan(1e9999)", + "ln(-1.0)", "log2(-1.0)", "log10(-1.0)", "log(-1.0, 2.0)", "powf(-1.0, 0.5)", + "fract(1e9999)", "rem_euclid(1.0, 0.0)", "rem_euclid(1e9999, 2.0)"}) { + CAPTURE(text); + CHECK(std::isnan(evaluate(text))); + } + CHECK(evaluate("ln(0.0)") == -std::numeric_limits::infinity()); + CHECK(evaluate("recip(-0.0)") == -std::numeric_limits::infinity()); + CHECK(evaluate("recip(0.0)") == std::numeric_limits::infinity()); + CHECK(evaluate("exp(1e9999)") == std::numeric_limits::infinity()); + CHECK(evaluate("powf(0.0 / 0.0, 0.0)") == 1.0); +} + +TEST_CASE("rounding preserves signed zeros boundaries and ties without changing the environment") { + const int original = std::fegetround(); + REQUIRE(original != -1); + // Each mode must yield the same nearest-even results, with no environment mutation. + for (int mode : {FE_TONEAREST, FE_DOWNWARD, FE_UPWARD, FE_TOWARDZERO}) { + REQUIRE(std::fesetround(mode) == 0); + for (const auto& [text, expected] : std::array{ + std::pair{"round_ties_even(0.5)", 0.0}, std::pair{"round_ties_even(-0.5)", -0.0}, + std::pair{"round_ties_even(1.5)", 2.0}, std::pair{"round_ties_even(2.5)", 2.0}, + std::pair{"round_ties_even(3.5)", 4.0}, std::pair{"round_ties_even(-2.5)", -2.0}, + std::pair{"round_ties_even(-3.5)", -4.0}, + std::pair{"round_ties_even(0.49999999999999994)", 0.0}, + std::pair{"round_ties_even(0.5000000000000001)", 1.0}, + std::pair{"round_ties_even(4503599627370495.5)", 4503599627370496.0}, + std::pair{"round_ties_even(4503599627370496.0)", 4503599627370496.0}}) { + CAPTURE(mode); + CAPTURE(text); + const auto actual = evaluate(text); + CHECK(actual == expected); + CHECK(std::signbit(actual) == std::signbit(expected)); + } + CHECK(std::isinf(evaluate("round_ties_even(1e9999)"))); + CHECK(std::isnan(evaluate("round_ties_even(0.0 / 0.0)"))); + CHECK(std::fegetround() == mode); + } + REQUIRE(std::fesetround(original) == 0); + CHECK(std::signbit(evaluate("round(-0.25)"))); + CHECK(std::signbit(evaluate("trunc(-0.25)"))); + CHECK(std::signbit(evaluate("sqrt(-0.0)"))); + CHECK(std::signbit(evaluate("sin(-0.0)"))); +} + +TEST_CASE("Euclidean remainders use divisor magnitude and permit rounded upper bounds") { + CHECK(evaluate("rem_euclid(-7.0, -4.0)") == 1.0); + CHECK(evaluate("rem_euclid(7.0, -4.0)") == 3.0); + CHECK(evaluate("rem_euclid(-1e-100, 1.0)") == 1.0); + CHECK(std::signbit(evaluate("rem_euclid(-0.0, 2.0)"))); + CHECK(evaluate("rem_euclid(3.0, 1e9999)") == 3.0); + CHECK(std::isinf(evaluate("rem_euclid(-3.0, 1e9999)"))); +} + +TEST_CASE("mul_add has one rounding step rather than a rounded intermediate product") { + CHECK(evaluate("mul_add(1.0000000000000002, 0.9999999999999998, -1.0)") == + -4.930380657631324e-32); + CHECK(std::signbit(evaluate("copysign(0.0, -1.0)"))); +} From f92495a058d2dbfada40822a5c5c63722e8f9bcd Mon Sep 17 00:00:00 2001 From: Sean Parent <160927019+sparent_adobe@users.noreply.github.com> Date: Fri, 13 Nov 2026 13:31:17 -0800 Subject: [PATCH 2/4] docs: add tutorial reference and verified package consumers Build Doxygen through cpp-library, link all retained operation contracts to the CEL book, and exercise source and installed consumers. Include repeatable CI, deterministic static analysis, and license notices. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .clang-tidy | 2 + .github/workflows/ci.yml | 128 +++++++ .vscode/extensions.json | 8 + .vscode/settings.json | 5 + .vscode/tasks.json | 333 ++++++++++++++++++ CMakeLists.txt | 27 ++ LICENSE | 23 ++ README.md | 72 +++- docs/index.html | 15 + docs/reference.dox | 85 +++++ docs/superpowers/plans/2026-11-13-f64-port.md | 28 +- docs/tutorial.md | 95 +++++ examples/example.cpp | 24 ++ include/cel/std.hpp | 3 + licenses/CPM-MIT.txt | 21 ++ src/std.cpp | 5 +- tests/consumer.cmake.in | 38 ++ tests/consumer/CMakeLists.txt | 14 + tests/consumer/main.cpp | 19 + tests/std_test.cpp | 5 + 20 files changed, 931 insertions(+), 19 deletions(-) create mode 100644 .clang-tidy create mode 100644 .github/workflows/ci.yml create mode 100644 .vscode/extensions.json create mode 100644 .vscode/settings.json create mode 100644 .vscode/tasks.json create mode 100644 LICENSE create mode 100644 docs/index.html create mode 100644 docs/reference.dox create mode 100644 docs/tutorial.md create mode 100644 examples/example.cpp create mode 100644 licenses/CPM-MIT.txt create mode 100644 tests/consumer.cmake.in create mode 100644 tests/consumer/CMakeLists.txt create mode 100644 tests/consumer/main.cpp diff --git a/.clang-tidy b/.clang-tidy new file mode 100644 index 0000000..4b5a428 --- /dev/null +++ b/.clang-tidy @@ -0,0 +1,2 @@ +Checks: '-*,clang-analyzer-*' +WarningsAsErrors: '*' diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..64f4ff1 --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,128 @@ +# Adapted from cpp-library's CI template. + +name: CI + +on: + push: + branches: [main, feat/f64-port] + pull_request: + branches: [main] + release: + types: [published] + +permissions: + contents: read + +jobs: + test: + name: Test (${{ matrix.name }}) + strategy: + fail-fast: false + matrix: + include: + - name: Ubuntu GCC + os: ubuntu-latest + cc: gcc + cxx: g++ + - name: Ubuntu Clang + os: ubuntu-latest + cc: clang + cxx: clang++ + - name: macOS + os: macos-latest + - name: Windows + os: windows-latest + + runs-on: ${{ matrix.os }} + + steps: + - uses: actions/checkout@v7 + - if: ${{ startsWith(matrix.os, 'windows') }} + uses: ilammy/msvc-dev-cmd@0b201ec74fa43914dc39ae48a89fd1d8cb592756 + + - name: Configure CMake + run: cmake --preset=test + env: + CC: ${{ matrix.cc }} + CXX: ${{ matrix.cxx }} + if: ${{ matrix.cc }} + + - name: Configure CMake + run: cmake --preset=test + if: ${{ !matrix.cc }} + + - name: Build + run: cmake --build --preset=test + + - name: Test + run: ctest --preset=test + + - name: Build and Install + run: | + cmake --preset=default + cmake --build --preset=default + cmake --install build/default --prefix ${{ runner.temp }}/install + env: + CC: ${{ matrix.cc }} + CXX: ${{ matrix.cxx }} + if: ${{ matrix.cc }} + + - name: Build and Install + run: | + cmake --preset=default + cmake --build --preset=default + cmake --install build/default --prefix ${{ runner.temp }}/install + if: ${{ !matrix.cc }} + + - name: Test find_package + shell: bash + run: | + # Create a minimal test to verify the installation works with find_package + mkdir -p ${{ runner.temp }}/test-find-package + cd ${{ runner.temp }}/test-find-package + + # Create test CMakeLists.txt + cat > CMakeLists.txt << EOF + cmake_minimum_required(VERSION 3.20) + project(test-find-package CXX) + + find_package(cel-std REQUIRED) + + message(STATUS "Successfully found cel-std") + EOF + + # Convert paths to forward slashes for CMake (works on all platforms) + INSTALL_PREFIX=$(echo '${{ runner.temp }}/install' | sed 's|\\|/|g') + + # Test find_package with CMAKE_PREFIX_PATH + cmake -B build -S . -DCMAKE_PREFIX_PATH="${INSTALL_PREFIX}" + + clang-tidy: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v7 + + - name: Configure CMake with clang-tidy + run: cmake --preset=clang-tidy + + - name: Build with clang-tidy + run: cmake --build --preset=clang-tidy + + - name: Run tests with clang-tidy + run: ctest --preset=clang-tidy + + docs: + runs-on: ubuntu-latest + + steps: + - uses: actions/checkout@v7 + + - name: Install Doxygen + uses: ssciwr/doxygen-install@fa3e94d34131d3990b6b8ba939ab982964aa3758 + + - name: Configure CMake + run: cmake --preset=docs + + - name: Build Documentation + run: cmake --build --preset=docs diff --git a/.vscode/extensions.json b/.vscode/extensions.json new file mode 100644 index 0000000..1fa1d19 --- /dev/null +++ b/.vscode/extensions.json @@ -0,0 +1,8 @@ +{ + "recommendations": [ + "matepek.vscode-catch2-test-adapter", + "llvm-vs-code-extensions.vscode-clangd", + "ms-vscode.live-server", + "ms-vscode.cmake-tools" + ] +} diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..1174fa4 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,5 @@ +{ + "cmake.useCMakePresets": "always", + "cmake.configureOnOpen": true, + "cmake.copyCompileCommands": "${workspaceFolder}/compile_commands.json" +} diff --git a/.vscode/tasks.json b/.vscode/tasks.json new file mode 100644 index 0000000..297e047 --- /dev/null +++ b/.vscode/tasks.json @@ -0,0 +1,333 @@ +{ + "version": "2.0.0", + "inputs": [ + { + "id": "setConfigurePreset-default", + "type": "command", + "command": "cmake.setConfigurePreset", + "args": "default" + }, + { + "id": "setConfigurePreset-test", + "type": "command", + "command": "cmake.setConfigurePreset", + "args": "test" + }, + { + "id": "setConfigurePreset-docs", + "type": "command", + "command": "cmake.setConfigurePreset", + "args": "docs" + }, + { + "id": "setConfigurePreset-clang-tidy", + "type": "command", + "command": "cmake.setConfigurePreset", + "args": "clang-tidy" + }, + { + "id": "setConfigurePreset-init", + "type": "command", + "command": "cmake.setConfigurePreset", + "args": "init" + }, + { + "id": "setConfigurePreset-install", + "type": "command", + "command": "cmake.setConfigurePreset", + "args": "install" + }, + { + "id": "setBuildPreset-default", + "type": "command", + "command": "cmake.setBuildPreset", + "args": "default" + }, + { + "id": "setBuildPreset-test", + "type": "command", + "command": "cmake.setBuildPreset", + "args": "test" + }, + { + "id": "setBuildPreset-docs", + "type": "command", + "command": "cmake.setBuildPreset", + "args": "docs" + }, + { + "id": "setBuildPreset-clang-tidy", + "type": "command", + "command": "cmake.setBuildPreset", + "args": "clang-tidy" + }, + { + "id": "setBuildPreset-init", + "type": "command", + "command": "cmake.setBuildPreset", + "args": "init" + }, + { + "id": "setBuildPreset-install", + "type": "command", + "command": "cmake.setBuildPreset", + "args": "install" + }, + { + "id": "setTestPreset-test", + "type": "command", + "command": "cmake.setTestPreset", + "args": "test" + }, + { + "id": "setTestPreset-clang-tidy", + "type": "command", + "command": "cmake.setTestPreset", + "args": "clang-tidy" + } + ], + "tasks": [ + // ============ CMake Preset Tasks ============ + { + "label": "Configure & Build: Default Configuration", + "type": "shell", + "command": "cmake --preset default && cmake --build --preset default", + "options": { + "env": { + "CMAKE_TOOLS_SYNC": "${input:setConfigurePreset-default} ${input:setBuildPreset-default}" + } + }, + "group": { + "kind": "build", + "isDefault": true + }, + "problemMatcher": [ + "$gcc", + "$msCompile" + ], + "detail": "Default configuration for building the library Requires the CMake Tools extension (ms-vscode.cmake-tools) — without it, this task fails to start.", + "windows": { + "options": { + "shell": { + "executable": "cmd.exe", + "args": [ + "/d", + "/c" + ] + } + } + } + }, + { + "label": "Configure & Build: Test Configuration", + "type": "shell", + "command": "cmake --preset test && cmake --build --preset test", + "options": { + "env": { + "CMAKE_TOOLS_SYNC": "${input:setConfigurePreset-test} ${input:setBuildPreset-test}" + } + }, + "group": "build", + "problemMatcher": [ + "$gcc", + "$msCompile" + ], + "detail": "Configuration for building and running tests Requires the CMake Tools extension (ms-vscode.cmake-tools) — without it, this task fails to start.", + "windows": { + "options": { + "shell": { + "executable": "cmd.exe", + "args": [ + "/d", + "/c" + ] + } + } + } + }, + { + "label": "Configure & Build: Documentation Configuration", + "type": "shell", + "command": "cmake --preset docs && cmake --build --preset docs", + "options": { + "env": { + "CMAKE_TOOLS_SYNC": "${input:setConfigurePreset-docs} ${input:setBuildPreset-docs}" + } + }, + "group": "build", + "problemMatcher": [ + "$gcc", + "$msCompile" + ], + "detail": "Configuration for building documentation Requires the CMake Tools extension (ms-vscode.cmake-tools) — without it, this task fails to start.", + "windows": { + "options": { + "shell": { + "executable": "cmd.exe", + "args": [ + "/d", + "/c" + ] + } + } + } + }, + { + "label": "Configure & Build: Clang-Tidy Configuration", + "type": "shell", + "command": "cmake --preset clang-tidy && cmake --build --preset clang-tidy", + "options": { + "env": { + "CMAKE_TOOLS_SYNC": "${input:setConfigurePreset-clang-tidy} ${input:setBuildPreset-clang-tidy}" + } + }, + "group": "build", + "problemMatcher": [ + "$gcc", + "$msCompile" + ], + "detail": "Configuration for running clang-tidy static analysis Requires the CMake Tools extension (ms-vscode.cmake-tools) — without it, this task fails to start.", + "windows": { + "options": { + "shell": { + "executable": "cmd.exe", + "args": [ + "/d", + "/c" + ] + } + } + } + }, + { + "label": "Configure & Build: Initialize Templates", + "type": "shell", + "command": "cmake --preset init && cmake --build --preset init", + "options": { + "env": { + "CMAKE_TOOLS_SYNC": "${input:setConfigurePreset-init} ${input:setBuildPreset-init}" + } + }, + "group": "build", + "problemMatcher": [ + "$gcc", + "$msCompile" + ], + "detail": "Force regeneration of template files (CMakePresets.json, CI, etc.) Requires the CMake Tools extension (ms-vscode.cmake-tools) — without it, this task fails to start.", + "windows": { + "options": { + "shell": { + "executable": "cmd.exe", + "args": [ + "/d", + "/c" + ] + } + } + } + }, + { + "label": "Configure & Build: Install Configuration", + "type": "shell", + "command": "cmake --preset install && cmake --build --preset install", + "options": { + "env": { + "CMAKE_TOOLS_SYNC": "${input:setConfigurePreset-install} ${input:setBuildPreset-install}" + } + }, + "group": "build", + "problemMatcher": [ + "$gcc", + "$msCompile" + ], + "detail": "Release build for installation with CPM_USE_LOCAL_PACKAGES enabled for testing installed packages Requires the CMake Tools extension (ms-vscode.cmake-tools) — without it, this task fails to start.", + "windows": { + "options": { + "shell": { + "executable": "cmd.exe", + "args": [ + "/d", + "/c" + ] + } + } + } + }, + { + "label": "Build & Test: Run All Tests", + "type": "shell", + "command": "cmake --preset test && cmake --build --preset test && ctest --preset test", + "options": { + "env": { + "CMAKE_TOOLS_SYNC": "${input:setConfigurePreset-test} ${input:setBuildPreset-test} ${input:setTestPreset-test}" + } + }, + "group": { + "kind": "test", + "isDefault": true + }, + "problemMatcher": [ + "$gcc", + "$msCompile" + ], + "detail": "Configuration for building and running tests Requires the CMake Tools extension (ms-vscode.cmake-tools) — without it, this task fails to start.", + "windows": { + "options": { + "shell": { + "executable": "cmd.exe", + "args": [ + "/d", + "/c" + ] + } + } + } + }, + { + "label": "Build & Test: Run Tests with Clang-Tidy", + "type": "shell", + "command": "cmake --preset clang-tidy && cmake --build --preset clang-tidy && ctest --preset clang-tidy", + "options": { + "env": { + "CMAKE_TOOLS_SYNC": "${input:setConfigurePreset-clang-tidy} ${input:setBuildPreset-clang-tidy} ${input:setTestPreset-clang-tidy}" + } + }, + "group": "test", + "problemMatcher": [ + "$gcc", + "$msCompile" + ], + "detail": "Configuration for running clang-tidy static analysis Requires the CMake Tools extension (ms-vscode.cmake-tools) — without it, this task fails to start.", + "windows": { + "options": { + "shell": { + "executable": "cmd.exe", + "args": [ + "/d", + "/c" + ] + } + } + } + }, + // ============ Cleanup Tasks ============ + { + "label": "Clean Build Directory (Active Config)", + "type": "shell", + "command": "cmake -E rm -rf \"${command:cmake.buildDirectory}\"", + "detail": "Deletes the build directory for the CMake Tools extension's currently active configure preset. Requires the CMake Tools extension with an active preset selected." + }, + { + "label": "Clean Build Directory (All Presets)", + "type": "shell", + "command": "cmake -E rm -rf \"${workspaceFolder}/build\"", + "detail": "Deletes the entire build/ directory, covering every preset's binary directory." + }, + { + "label": "Clean CPM Cache", + "type": "shell", + "command": "cmake -E rm -rf \"${workspaceFolder}/.cache/cpm\"", + "detail": "Deletes the CPM dependency source cache (CPM_SOURCE_CACHE)." + } + ] +} diff --git a/CMakeLists.txt b/CMakeLists.txt index 0e7df79..4fb713b 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -7,6 +7,7 @@ cpp_library_enable_dependency_tracking() project(std LANGUAGES CXX) set(CMAKE_CXX_EXTENSIONS OFF) +include(GNUInstallDirs) if(PROJECT_IS_TOP_LEVEL) include(CTest) endif() @@ -28,6 +29,32 @@ cpp_library_setup( HEADERS std.hpp SOURCES std.cpp TESTS std_test.cpp + EXAMPLES example.cpp + DOCS_INPUTS README.md docs/tutorial.md docs/reference.dox + DOCS_OPTIONS + "USE_MDFILE_AS_MAINPAGE = ${CMAKE_CURRENT_SOURCE_DIR}/README.md" + "EXCLUDE_SYMBOLS = cel::op_lookup" + "WARN_AS_ERROR = YES" + "FULL_PATH_NAMES = NO" + "STRIP_FROM_PATH = ${CMAKE_CURRENT_SOURCE_DIR}" + "STRIP_FROM_INC_PATH = ${CMAKE_CURRENT_SOURCE_DIR}/include" ) cpp_library_map_dependency("cel::parser" "cel-parser CONFIG") target_link_libraries(std PUBLIC cel::parser) +if(CEL_INSTALL) + install(FILES LICENSE licenses/CPM-MIT.txt + DESTINATION "${CMAKE_INSTALL_DATADIR}/licenses/cel-std") +endif() + +if(PROJECT_IS_TOP_LEVEL AND BUILD_TESTING) + configure_file(tests/consumer.cmake.in consumer.cmake @ONLY) + foreach(mode source installed) + if(mode STREQUAL "installed" AND NOT CEL_INSTALL) + continue() + endif() + add_test(NAME consumer_${mode} + COMMAND "${CMAKE_COMMAND}" "-DMODE=${mode}" "-DCONFIG=$" + -P "${CMAKE_CURRENT_BINARY_DIR}/consumer.cmake") + set_tests_properties(consumer_${mode} PROPERTIES TIMEOUT 300) + endforeach() +endif() diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..36b7cd9 --- /dev/null +++ b/LICENSE @@ -0,0 +1,23 @@ +Boost Software License - Version 1.0 - August 17th, 2003 + +Permission is hereby granted, free of charge, to any person or organization +obtaining a copy of the software and accompanying documentation covered by +this license (the "Software") to use, reproduce, display, distribute, +execute, and transmit the Software, and to prepare derivative works of the +Software, and to permit third-parties to whom the Software is furnished to +do so, all subject to the following: + +The copyright notices in the Software and this entire statement, including +the above license grant, this restriction and the following disclaimer, +must be included in all copies of the Software, in whole or in part, and +all derivative works of the Software, unless such copies or derivative +works are solely in the form of machine-executable object code generated by +a source language processor. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE, TITLE AND NON-INFRINGEMENT. IN NO EVENT +SHALL THE COPYRIGHT HOLDERS OR ANYONE DISTRIBUTING THE SOFTWARE BE LIABLE +FOR ANY DAMAGES OR OTHER LIABILITY, WHETHER IN CONTRACT, TORT OR OTHERWISE, +ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/README.md b/README.md index 61f5151..429c37a 100644 --- a/README.md +++ b/README.md @@ -1,2 +1,72 @@ # cel-std -C++ f64 CEL standard library for cel-parser and cel-runtime + +`cel-std` installs numeric operations into the C++ [CEL parser]( +https://github.com/stlab/cel-parser) for execution by [CEL runtime]( +https://github.com/stlab/cel-runtime). Use it when your C++ application needs +CEL expressions such as `clamp(sqrt(9.0), 0.0, 4.0)`. + +This port retains 35 Rust `cel-std` operations with `f64` (`double`) operands. +It excludes `powi`, all integer overloads, and all `f32` overloads. +`sin_cos` returns a CEL `(f64, f64)` tuple. Ordinary and receiver calls use +the same registrations. + +## Add the library + +Use C++20 and CMake 3.24 or later. After loading [CPM]( +https://github.com/cpm-cmake/CPM.cmake), add the library to your project: + +```cmake +CPMAddPackage( + NAME cel-std + GITHUB_REPOSITORY stlab/cel-std + GIT_TAG feat/f64-port +) +target_link_libraries(your_app PRIVATE cel::std) +``` + +Replace `your_app` with your executable target. The feature branch contains +the initial port; pin a reviewed commit for reproducible builds. +The library brings in compatible, pinned parser and runtime dependencies. + +Include `` and ``, create a +`cel::op_lookup`, and call `cel::stdlib::install(lookup)` before transferring +the lookup into a parser. See the [tutorial](docs/tutorial.md) for a complete, +compiled example and installed-package instructions. + +## Build and test + +Configure, build, and run all unit, example, and consumer tests: + +```sh +cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_DOCS=OFF +cmake --build build --parallel +ctest --test-dir build --output-on-failure +``` + +Generate the tutorial and API reference with Doxygen 1.13.1 or later: + +```sh +cmake -S . -B build/docs -DBUILD_DOCS=ON -DBUILD_TESTING=OFF +cmake --build build/docs --target docs +``` + +Open `build/docs/html/index.html`. + +## Documentation + +The [tutorial](docs/tutorial.md) teaches installation, parsing, execution, +and tuple results. The [reference](docs/reference.dox) lists the C++ interface +and retained signatures. For operation behavior and examples, see the +[CEL language book's standard library]( +https://stlab.github.io/cel-rs/cel-book/standard-library.html). +The book also covers Rust types and `powi` that this port does not provide. + +The implementation uses the C++ standard library and small adapters for +Rust semantics. Build without fast-math modes that discard NaNs, signed zeros, +or IEEE arithmetic. Approximate transcendental results can differ across +standard libraries; NaN payloads are not part of the contract. + +## License + +Boost Software License 1.0. The CPM bootstrap is MIT-licensed; see +`licenses/CPM-MIT.txt`. diff --git a/docs/index.html b/docs/index.html new file mode 100644 index 0000000..1d87364 --- /dev/null +++ b/docs/index.html @@ -0,0 +1,15 @@ + + + + + + + + Redirecting to Documentation + + + +

If you are not redirected automatically, click here.

+ + + diff --git a/docs/reference.dox b/docs/reference.dox new file mode 100644 index 0000000..e51b3bc --- /dev/null +++ b/docs/reference.dox @@ -0,0 +1,85 @@ +/** +\page reference Library reference + +Use this reference to select the C++ installation interface or look up a retained +CEL signature. Operation links point to the CEL language book, which defines +numeric behavior, error conditions, and examples. + +\section package Package and installer + +The CMake package is `cel-std`; its exported target is `cel::std`. +The public header is ``. +Call cel::stdlib::install with a `cel::op_lookup` before constructing your parser. +See \ref tutorial for a compiled example. + +The installer registers persistent ordinary and receiver-call signatures. +The receiver supplies the first operand; no numeric conversions are introduced. +Independent libraries can register disjoint overloads before or after installation. +Install each exact standard-library signature only once per lookup. + +\section signatures Retained CEL signatures + +Every `f64` maps to C++ `double`. Scalar result types remain `f64`, including +rounding operations. `sin_cos` returns a structural tuple whose C++ adapter is +`std::tuple`. + +The following table is the entire port, not the book's larger Rust type set: + +| CEL signature | Operation contract | +| --- | --- | +| `min(a: f64, b: f64) -> f64` | [min](https://stlab.github.io/cel-rs/cel-book/standard-library.html#min) | +| `max(a: f64, b: f64) -> f64` | [max](https://stlab.github.io/cel-rs/cel-book/standard-library.html#max) | +| `clamp(x: f64, lo: f64, hi: f64) -> f64` | [clamp](https://stlab.github.io/cel-rs/cel-book/standard-library.html#clamp) | +| `abs(x: f64) -> f64` | [abs](https://stlab.github.io/cel-rs/cel-book/standard-library.html#abs) | +| `signum(x: f64) -> f64` | [signum](https://stlab.github.io/cel-rs/cel-book/standard-library.html#signum) | +| `sqrt(x: f64) -> f64` | [sqrt](https://stlab.github.io/cel-rs/cel-book/standard-library.html#sqrt) | +| `floor(x: f64) -> f64` | [floor](https://stlab.github.io/cel-rs/cel-book/standard-library.html#floor) | +| `ceil(x: f64) -> f64` | [ceil](https://stlab.github.io/cel-rs/cel-book/standard-library.html#ceil) | +| `trunc(x: f64) -> f64` | [trunc](https://stlab.github.io/cel-rs/cel-book/standard-library.html#trunc) | +| `fract(x: f64) -> f64` | [fract](https://stlab.github.io/cel-rs/cel-book/standard-library.html#fract) | +| `round_ties_even(x: f64) -> f64` | [round_ties_even](https://stlab.github.io/cel-rs/cel-book/standard-library.html#round-ties-even) | +| `round(x: f64) -> f64` | [round](https://stlab.github.io/cel-rs/cel-book/standard-library.html#round) | +| `sin(x: f64) -> f64` | [sin](https://stlab.github.io/cel-rs/cel-book/standard-library.html#sin) | +| `cos(x: f64) -> f64` | [cos](https://stlab.github.io/cel-rs/cel-book/standard-library.html#cos) | +| `tan(x: f64) -> f64` | [tan](https://stlab.github.io/cel-rs/cel-book/standard-library.html#tan) | +| `asin(x: f64) -> f64` | [asin](https://stlab.github.io/cel-rs/cel-book/standard-library.html#asin) | +| `acos(x: f64) -> f64` | [acos](https://stlab.github.io/cel-rs/cel-book/standard-library.html#acos) | +| `atan(x: f64) -> f64` | [atan](https://stlab.github.io/cel-rs/cel-book/standard-library.html#atan) | +| `atan2(y: f64, x: f64) -> f64` | [atan2](https://stlab.github.io/cel-rs/cel-book/standard-library.html#atan2) | +| `sin_cos(x: f64) -> (f64, f64)` | [sin_cos](https://stlab.github.io/cel-rs/cel-book/standard-library.html#sin-cos) | +| `to_radians(x: f64) -> f64` | [to_radians](https://stlab.github.io/cel-rs/cel-book/standard-library.html#to-radians) | +| `to_degrees(x: f64) -> f64` | [to_degrees](https://stlab.github.io/cel-rs/cel-book/standard-library.html#to-degrees) | +| `hypot(x: f64, y: f64) -> f64` | [hypot](https://stlab.github.io/cel-rs/cel-book/standard-library.html#hypot) | +| `cbrt(x: f64) -> f64` | [cbrt](https://stlab.github.io/cel-rs/cel-book/standard-library.html#cbrt) | +| `powf(x: f64, exponent: f64) -> f64` | [powf](https://stlab.github.io/cel-rs/cel-book/standard-library.html#powf) | +| `exp(x: f64) -> f64` | [exp](https://stlab.github.io/cel-rs/cel-book/standard-library.html#exp) | +| `exp2(x: f64) -> f64` | [exp2](https://stlab.github.io/cel-rs/cel-book/standard-library.html#exp2) | +| `ln(x: f64) -> f64` | [ln](https://stlab.github.io/cel-rs/cel-book/standard-library.html#ln) | +| `log(x: f64, base: f64) -> f64` | [log](https://stlab.github.io/cel-rs/cel-book/standard-library.html#log) | +| `log2(x: f64) -> f64` | [log2](https://stlab.github.io/cel-rs/cel-book/standard-library.html#log2) | +| `log10(x: f64) -> f64` | [log10](https://stlab.github.io/cel-rs/cel-book/standard-library.html#log10) | +| `recip(x: f64) -> f64` | [recip](https://stlab.github.io/cel-rs/cel-book/standard-library.html#recip) | +| `mul_add(x: f64, multiplier: f64, addend: f64) -> f64` | [mul_add](https://stlab.github.io/cel-rs/cel-book/standard-library.html#mul-add) | +| `rem_euclid(x: f64, divisor: f64) -> f64` | [rem_euclid](https://stlab.github.io/cel-rs/cel-book/standard-library.html#rem-euclid) | +| `copysign(magnitude: f64, sign: f64) -> f64` | [copysign](https://stlab.github.io/cel-rs/cel-book/standard-library.html#copysign) | + +No `powi`, integer, or `f32` signature is installed. Those parts of the linked +book describe Rust capabilities outside this port. + +\section floating Floating-point environment + +Build for IEEE 754 binary64 without fast-math assumptions. +The implementation uses C++ standard-library math and preserves the book's +documented NaN, infinity, signed-zero, and rounding behavior. Transcendental +results need not be bit-identical across implementations; compare them using a +tolerance. NaN payloads and signs are unspecified. + +`round_ties_even` is independent of the ambient rounding mode and does not +change that mode. The library does not promise to preserve floating-point +exception flags or `errno`. + +During evaluation, invalid clamp bounds throw +`std::invalid_argument("invalid clamp bounds")`. Other numeric domain failures +produce the floating-point results documented in the book. Unsupported +signatures are parser compilation errors. +*/ diff --git a/docs/superpowers/plans/2026-11-13-f64-port.md b/docs/superpowers/plans/2026-11-13-f64-port.md index 2fd289a..50eaea4 100644 --- a/docs/superpowers/plans/2026-11-13-f64-port.md +++ b/docs/superpowers/plans/2026-11-13-f64-port.md @@ -49,19 +49,19 @@ cel-runtime owns and executes the emitted operations. **Consumes:** Parser registration APIs and runtime native tuple adapters. **Produces:** `void cel::stdlib::install(cel::op_lookup&)`, target `cel::std`. -- [ ] Inspect the exact parser registration API and cpp-library setup before scaffolding. -- [ ] Write `std_test.cpp`: ordinary/receiver calls for every listed operation, +- [x] Inspect the exact parser registration API and cpp-library setup before scaffolding. +- [x] Write `std_test.cpp`: ordinary/receiver calls for every listed operation, assert `atan2(1.0, -1.0)` is approximately 3*pi/4, `log(8.0, 2.0)` is approximately 3, and `sin_cos(0.0)` is the tuple `(0.0, 1.0)`. -- [ ] Configure the project and run the test build; confirm the installer is absent. -- [ ] Implement the public header and installer with private, contracted adapters. -- [ ] Add and run edge tests: `signum(-0.0) == -1.0`, NaN min/max operands, +- [x] Configure the project and run the test build; confirm the installer is absent. +- [x] Implement the public header and installer with private, contracted adapters. +- [x] Add and run edge tests: `signum(-0.0) == -1.0`, NaN min/max operands, invalid clamp bounds, signed zeros, infinities, exact FMA cancellation, `rem_euclid(-7.0, 4.0) == 1.0`, `fract(-1.25) == -0.25`, and ties-to-even in FE_TONEAREST/FE_DOWNWARD/FE_UPWARD/FE_TOWARDZERO. -- [ ] Add integration tests for closures, unrelated registrations, parser lifetime, +- [x] Add integration tests for closures, unrelated registrations, parser lifetime, tuple projection, and rejection of powi, wrong types, and wrong arities. -- [ ] Run `cmake --build build` and `ctest --test-dir build --output-on-failure`; +- [x] Run `cmake --build build` and `ctest --test-dir build --output-on-failure`; require all tests to pass, then commit the coherent implementation. ### Task 2: Consumer packaging and user documentation @@ -69,16 +69,16 @@ cel-runtime owns and executes the emitted operations. **Consumes:** Task 1's installer and target. **Produces:** Verified source/installed consumers, tutorial, reference, CI. -- [ ] Write a minimal independent consumer calling install, parsing +- [x] Write a minimal independent consumer calling install, parsing `sqrt(9.0)`, and asserting a prepared execution result of 3.0. -- [ ] Exercise the source and installed forms before adding missing export mappings; +- [x] Exercise the source and installed forms before adding missing export mappings; resolve package discovery with cpp-library's dependency mapping facilities. -- [ ] Verify the published CEL book URL and operation anchors. -- [ ] Write and compile the tutorial example; use it in the Doxygen tutorial. -- [ ] Write installer/package reference and an exact f64 signature table linking +- [x] Verify the published CEL book URL and operation anchors. +- [x] Write and compile the tutorial example; use it in the Doxygen tutorial. +- [x] Write installer/package reference and an exact f64 signature table linking each operation to its language-book entry; explicitly exclude powi and other types. -- [ ] Add CI using verified build/test/documentation commands, not assumed targets. -- [ ] Run all unit and consumer tests, format checks, Doxygen warnings checks, +- [x] Add CI using verified build/test/documentation commands, not assumed targets. +- [x] Run all unit and consumer tests, format checks, Doxygen warnings checks, and an available sanitizer configuration. Fix in-scope review findings. - [ ] Commit the documentation and packaging, push the feature branch, and report the repository, branch, worktree, check results, and any material limitations. diff --git a/docs/tutorial.md b/docs/tutorial.md new file mode 100644 index 0000000..9084e7b --- /dev/null +++ b/docs/tutorial.md @@ -0,0 +1,95 @@ +# Evaluate numeric CEL expressions {#tutorial} + +This tutorial shows C++ developers how to install the library, compile +expressions, and retrieve scalar and tuple results. For individual operation +semantics, use the [CEL language book's standard library]( +https://stlab.github.io/cel-rs/cel-book/standard-library.html). + +## Before you begin + +Use a C++20 compiler with IEEE 754 binary64 `double`, CMake 3.24 or later, +and CPM. Configure and build the library as described in the README. +The library depends on `cel::parser`, which supplies `cel::runtime`. +You do not need a separate runtime dependency declaration. + +## Compile and run an expression + +1. Link your executable against `cel::std`. +2. Include `` and ``. +3. Call `cel::stdlib::install(lookup)` before moving the lookup into a parser. +4. Compile an expression with `parse_str`. +5. Prepare its C++ result type and execute it with a caller-owned `cel::raw_stack`. + +The following complete program is built and run by the test suite: + +\include example.cpp + +The program prints: + +```text +3 +0, 1 +``` + +For a multi-configuration generator, select the build configuration when +building and running tests: + +```sh +cmake --build build --config Debug +ctest --test-dir build -C Debug --output-on-failure +``` + +## Use receiver calls and tuples + +`sqrt(9.0)` and `9.0.sqrt()` select the same operation. The receiver is +the first operand: `atan2(y, x)` is also `y.atan2(x)`. +The installed functions remain available inside CEL closure bodies. + +`sin_cos` produces a structural CEL tuple, not an opaque C++ object. +Prepare it as `std::tuple`, as the example shows. +In CEL, `sin_cos(0.0).0` selects sine and `.1` selects cosine. +The program owns its emitted operations and can outlive the parser. +The caller supplies exclusive access to each stack during execution. + +## Handle errors + +The parser rejects unsupported operand types, arities, and names during +compilation with `cel::parse_error`. Integer and `f32` overloads and `powi` +are not installed. + +During evaluation, `clamp` throws +`std::invalid_argument("invalid clamp bounds")` for reversed or NaN bounds. +Other floating-point domain failures return NaN or infinity as specified by +the language book; they do not become new C++ evaluation exceptions. +Allocation and dependency failures propagate to the caller. + +Install the library once per lookup. Existing registrations with disjoint +signatures remain usable; installation is not transactional if registration +fails. + +## Consume an installed package + +To install a release build, run: + +```sh +cmake -S . -B build/release -DCMAKE_BUILD_TYPE=Release \ + -DBUILD_TESTING=OFF -DBUILD_DOCS=OFF -DCEL_INSTALL=ON +cmake --build build/release --config Release +cmake --install build/release --config Release --prefix /PATH/TO/PREFIX +``` + +Replace `/PATH/TO/PREFIX` with your installation prefix. This installs the +standard library and its parser/runtime dependencies. + +In the consuming project, find the package and link its exported target: + +```cmake +find_package(cel-std CONFIG REQUIRED) +target_link_libraries(your_app PRIVATE cel::std) +``` + +Replace `your_app` with your executable target. Pass the installation prefix +as `-DCMAKE_PREFIX_PATH=/PATH/TO/PREFIX` when configuring the consumer. +Verify that the example produces the output shown in this tutorial. + +See the \ref reference for the complete retained signature table. diff --git a/examples/example.cpp b/examples/example.cpp new file mode 100644 index 0000000..2fbc690 --- /dev/null +++ b/examples/example.cpp @@ -0,0 +1,24 @@ +// SPDX-License-Identifier: BSL-1.0 +#include +#include +#include +#include +#include + +/// Installs the standard library and prints scalar and tuple expression results. +/// +/// Complexity: O(expression compilation and execution) time and program storage. +int main() { + cel::op_lookup lookup; + cel::stdlib::install(lookup); + cel::parser parser(std::move(lookup)); + cel::raw_stack stack; + + auto scalar = parser.parse_str("clamp(sqrt(9.0), 0.0, 4.0)"); + std::cout << scalar.prepare().call(stack) << '\n'; + + auto pair = parser.parse_str("0.0.sin_cos()"); + const auto [sine, cosine] = pair.prepare>().call(stack); + std::cout << sine << ", " << cosine << '\n'; + return 0; +} diff --git a/include/cel/std.hpp b/include/cel/std.hpp index ed0ced4..6956b9e 100644 --- a/include/cel/std.hpp +++ b/include/cel/std.hpp @@ -1,7 +1,10 @@ // SPDX-License-Identifier: BSL-1.0 +/// \file +/// Installs the f64 CEL standard library. #ifndef CEL_STD_HPP #define CEL_STD_HPP +/// Provides CEL compilation, runtime execution, and library extensions. namespace cel { class op_lookup; diff --git a/licenses/CPM-MIT.txt b/licenses/CPM-MIT.txt new file mode 100644 index 0000000..04abf87 --- /dev/null +++ b/licenses/CPM-MIT.txt @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2019-2023 Lars Melchior and contributors + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/src/std.cpp b/src/std.cpp index 2852a35..419e692 100644 --- a/src/std.cpp +++ b/src/std.cpp @@ -27,11 +27,8 @@ struct function_marker {}; template void add(cel::op_lookup& lookup, std::string_view name) { using result = std::invoke_result_t; - using marker = function_marker; lookup.register_op(name, Function); - lookup.register_function(name, marker{}); - lookup.register_op( - "()", [](marker, A... arguments) { return Function(arguments...); }); + lookup.register_function(name, function_marker{}); } /// Rounds to the nearest integer, selecting the even neighbor on a tie. diff --git a/tests/consumer.cmake.in b/tests/consumer.cmake.in new file mode 100644 index 0000000..687c900 --- /dev/null +++ b/tests/consumer.cmake.in @@ -0,0 +1,38 @@ +# Runs an independent source or installed consumer; any failed command is fatal. +# Complexity: O(consumer configuration, compilation, and execution). +function(run) + execute_process(COMMAND ${ARGV} COMMAND_ERROR_IS_FATAL ANY) +endfunction() + +set(root "@CMAKE_CURRENT_BINARY_DIR@/consumer-${MODE}") +set(options + "-DCMAKE_BUILD_TYPE=@CMAKE_BUILD_TYPE@" + "-DCMAKE_CXX_COMPILER=@CMAKE_CXX_COMPILER@" + "-DCMAKE_CXX_FLAGS=@CMAKE_CXX_FLAGS@" + "-DCMAKE_EXE_LINKER_FLAGS=@CMAKE_EXE_LINKER_FLAGS@") +set(build_config) +set(test_config) +if(CONFIG) + list(APPEND build_config --config "${CONFIG}") + list(APPEND test_config -C "${CONFIG}") +endif() + +if(MODE STREQUAL "source") + list(APPEND options "-DCEL_STD_SOURCE_DIR=@CMAKE_CURRENT_SOURCE_DIR@" + "-DBUILD_TESTING=OFF" "-DCEL_INSTALL=OFF") +elseif(MODE STREQUAL "installed") + run("@CMAKE_COMMAND@" --install "@CMAKE_CURRENT_BINARY_DIR@" + ${build_config} --prefix "${root}/prefix") + list(APPEND options + "-DCMAKE_PREFIX_PATH=${root}/prefix" + "-DCMAKE_FIND_USE_PACKAGE_REGISTRY=OFF" + "-DCMAKE_FIND_USE_SYSTEM_PACKAGE_REGISTRY=OFF") +else() + message(FATAL_ERROR "Unknown consumer mode: ${MODE}") +endif() + +run("@CMAKE_COMMAND@" -S "@CMAKE_CURRENT_SOURCE_DIR@/tests/consumer" + -B "${root}/build" -G "@CMAKE_GENERATOR@" ${options}) +run("@CMAKE_COMMAND@" --build "${root}/build" ${build_config} --parallel 2) +run("@CMAKE_CTEST_COMMAND@" --test-dir "${root}/build" + ${test_config} --output-on-failure) diff --git a/tests/consumer/CMakeLists.txt b/tests/consumer/CMakeLists.txt new file mode 100644 index 0000000..e433463 --- /dev/null +++ b/tests/consumer/CMakeLists.txt @@ -0,0 +1,14 @@ +cmake_minimum_required(VERSION 3.24) +project(cel_std_consumer LANGUAGES CXX) +enable_testing() + +if(CEL_STD_SOURCE_DIR) + include("${CEL_STD_SOURCE_DIR}/cmake/CPM.cmake") + CPMAddPackage(NAME cel-std SOURCE_DIR "${CEL_STD_SOURCE_DIR}") +else() + find_package(cel-std CONFIG REQUIRED) +endif() + +add_executable(consumer main.cpp) +target_link_libraries(consumer PRIVATE cel::std) +add_test(NAME consumer COMMAND consumer) diff --git a/tests/consumer/main.cpp b/tests/consumer/main.cpp new file mode 100644 index 0000000..7002950 --- /dev/null +++ b/tests/consumer/main.cpp @@ -0,0 +1,19 @@ +// SPDX-License-Identifier: BSL-1.0 +#include +#include +#include +#include + +/// Returns success when a standalone consumer can evaluate scalar and tuple operations. +/// +/// Complexity: O(expression compilation and execution) time and program storage. +int main() { + cel::op_lookup lookup; + cel::stdlib::install(lookup); + cel::parser parser(std::move(lookup)); + cel::raw_stack stack; + const auto scalar = parser.parse_str("sqrt(9.0)").prepare().call(stack); + const auto pair = + parser.parse_str("0.0.sin_cos()").prepare>().call(stack); + return scalar == 3.0 && pair == std::tuple{0.0, 1.0} ? 0 : 1; +} diff --git a/tests/std_test.cpp b/tests/std_test.cpp index d495bcb..1331f06 100644 --- a/tests/std_test.cpp +++ b/tests/std_test.cpp @@ -33,6 +33,9 @@ struct call_case { const char* receiver; ///< Equivalent CEL receiver call. double expected; ///< Expected result, within transcendental precision. }; + +/// Identifies an independently installed overload of the min function. +struct client_min {}; } // namespace TEST_CASE("each scalar operation preserves its name signature and argument order") { @@ -99,12 +102,14 @@ TEST_CASE("persistent library operations are visible in closure bodies") { TEST_CASE("installation preserves unrelated registrations and disjoint overloads") { cel::op_lookup lookup; lookup.register_op("twice", [](double x) { return x * 2.0; }); + lookup.register_function("min", client_min{}); lookup.register_op("min", [](bool a, bool b) { return a && b; }); cel::stdlib::install(lookup); cel::parser parser(std::move(lookup)); cel::raw_stack stack; CHECK(parser.parse_str("3.0.twice()").prepare().call(stack) == 6.0); CHECK_FALSE(parser.parse_str("true.min(false)").prepare().call(stack)); + CHECK_FALSE(parser.parse_str("min(true, false)").prepare().call(stack)); CHECK(parser.parse_str("min(2.0, 3.0)").prepare().call(stack) == 2.0); } From 7030f3b0fb217b9911ecae1f7ed8a24b38b1386d Mon Sep 17 00:00:00 2001 From: Sean Parent <160927019+sparent_adobe@users.noreply.github.com> Date: Fri, 13 Nov 2026 13:36:01 -0800 Subject: [PATCH 3/4] fix: preserve NaN clamp inputs and repair generated documentation links Keep NaN values outside std::clamp's ordering preconditions and validate bounds first. Use Markdown reference input so GitHub and Doxygen resolve the same navigation links. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- CMakeLists.txt | 2 +- README.md | 2 +- docs/{reference.dox => reference.md} | 12 +++++------- docs/superpowers/plans/2026-11-13-f64-port.md | 2 +- docs/tutorial.md | 2 +- src/std.cpp | 1 + tests/std_test.cpp | 4 ++-- 7 files changed, 12 insertions(+), 13 deletions(-) rename docs/{reference.dox => reference.md} (96%) diff --git a/CMakeLists.txt b/CMakeLists.txt index 4fb713b..ef4e53a 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -30,7 +30,7 @@ cpp_library_setup( SOURCES std.cpp TESTS std_test.cpp EXAMPLES example.cpp - DOCS_INPUTS README.md docs/tutorial.md docs/reference.dox + DOCS_INPUTS README.md docs/tutorial.md docs/reference.md DOCS_OPTIONS "USE_MDFILE_AS_MAINPAGE = ${CMAKE_CURRENT_SOURCE_DIR}/README.md" "EXCLUDE_SYMBOLS = cel::op_lookup" diff --git a/README.md b/README.md index 429c37a..b833b74 100644 --- a/README.md +++ b/README.md @@ -55,7 +55,7 @@ Open `build/docs/html/index.html`. ## Documentation The [tutorial](docs/tutorial.md) teaches installation, parsing, execution, -and tuple results. The [reference](docs/reference.dox) lists the C++ interface +and tuple results. The [reference](docs/reference.md) lists the C++ interface and retained signatures. For operation behavior and examples, see the [CEL language book's standard library]( https://stlab.github.io/cel-rs/cel-book/standard-library.html). diff --git a/docs/reference.dox b/docs/reference.md similarity index 96% rename from docs/reference.dox rename to docs/reference.md index e51b3bc..fa8ad35 100644 --- a/docs/reference.dox +++ b/docs/reference.md @@ -1,23 +1,22 @@ -/** -\page reference Library reference +# Library reference {#reference} Use this reference to select the C++ installation interface or look up a retained CEL signature. Operation links point to the CEL language book, which defines numeric behavior, error conditions, and examples. -\section package Package and installer +## Package and installer The CMake package is `cel-std`; its exported target is `cel::std`. The public header is ``. Call cel::stdlib::install with a `cel::op_lookup` before constructing your parser. -See \ref tutorial for a compiled example. +See the [tutorial](tutorial.md) for a compiled example. The installer registers persistent ordinary and receiver-call signatures. The receiver supplies the first operand; no numeric conversions are introduced. Independent libraries can register disjoint overloads before or after installation. Install each exact standard-library signature only once per lookup. -\section signatures Retained CEL signatures +## Retained CEL signatures Every `f64` maps to C++ `double`. Scalar result types remain `f64`, including rounding operations. `sin_cos` returns a structural tuple whose C++ adapter is @@ -66,7 +65,7 @@ The following table is the entire port, not the book's larger Rust type set: No `powi`, integer, or `f32` signature is installed. Those parts of the linked book describe Rust capabilities outside this port. -\section floating Floating-point environment +## Floating-point environment Build for IEEE 754 binary64 without fast-math assumptions. The implementation uses C++ standard-library math and preserves the book's @@ -82,4 +81,3 @@ During evaluation, invalid clamp bounds throw `std::invalid_argument("invalid clamp bounds")`. Other numeric domain failures produce the floating-point results documented in the book. Unsupported signatures are parser compilation errors. -*/ diff --git a/docs/superpowers/plans/2026-11-13-f64-port.md b/docs/superpowers/plans/2026-11-13-f64-port.md index 50eaea4..550623e 100644 --- a/docs/superpowers/plans/2026-11-13-f64-port.md +++ b/docs/superpowers/plans/2026-11-13-f64-port.md @@ -40,7 +40,7 @@ cel-runtime owns and executes the emitted operations. - `tests/std_test.cpp`: contract-derived numeric and parser integration tests. - `tests/consumer/`, `tests/consumer.cmake.in`: independent package/source consumers. - `examples/example.cpp`: runnable tutorial example. -- `README.md`, `docs/tutorial.md`, `docs/reference.dox`: orientation, tutorial, reference. +- `README.md`, `docs/tutorial.md`, `docs/reference.md`: orientation, tutorial, reference. - `.github/workflows/ci.yml`, `.gitignore`, `LICENSE`, formatting configuration: repository conventions and repeatable checks. diff --git a/docs/tutorial.md b/docs/tutorial.md index 9084e7b..fe95e10 100644 --- a/docs/tutorial.md +++ b/docs/tutorial.md @@ -92,4 +92,4 @@ Replace `your_app` with your executable target. Pass the installation prefix as `-DCMAKE_PREFIX_PATH=/PATH/TO/PREFIX` when configuring the consumer. Verify that the example produces the output shown in this tutorial. -See the \ref reference for the complete retained signature table. +See the [library reference](reference.md) for the complete retained signature table. diff --git a/src/std.cpp b/src/std.cpp index 419e692..84a9867 100644 --- a/src/std.cpp +++ b/src/std.cpp @@ -50,6 +50,7 @@ double rem_euclid(double x, double divisor) { /// Throws std::invalid_argument("invalid clamp bounds") for reversed or NaN bounds. double clamp(double x, double lower, double upper) { if (!(lower <= upper)) throw std::invalid_argument("invalid clamp bounds"); + if (std::isnan(x)) return x; return std::clamp(x, lower, upper); } } // namespace diff --git a/tests/std_test.cpp b/tests/std_test.cpp index 1331f06..2c32d0f 100644 --- a/tests/std_test.cpp +++ b/tests/std_test.cpp @@ -126,8 +126,8 @@ TEST_CASE("the subset rejects powi unsupported operand types and wrong arities") } TEST_CASE("clamp validates bounds and otherwise preserves Rust floating behavior") { - for (auto text : - {"clamp(1.0, 3.0, 2.0)", "clamp(1.0, 0.0 / 0.0, 2.0)", "clamp(1.0, 0.0, 0.0 / 0.0)"}) { + for (auto text : {"clamp(1.0, 3.0, 2.0)", "clamp(0.0 / 0.0, 3.0, 2.0)", + "clamp(1.0, 0.0 / 0.0, 2.0)", "clamp(1.0, 0.0, 0.0 / 0.0)"}) { CAPTURE(text); CHECK_THROWS_WITH_AS(evaluate(text), "invalid clamp bounds", std::invalid_argument); } From 7f692612b57df49a6e35b03b7fcc2f3eeec61dfd Mon Sep 17 00:00:00 2001 From: Sean Parent <160927019+sparent_adobe@users.noreply.github.com> Date: Fri, 13 Nov 2026 13:39:46 -0800 Subject: [PATCH 4/4] docs: record completed port and integration handoff Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .../2026-11-13-f64-port-handoff.md | 35 +++++++++++++++++++ docs/superpowers/plans/2026-11-13-f64-port.md | 2 +- 2 files changed, 36 insertions(+), 1 deletion(-) create mode 100644 docs/superpowers/2026-11-13-f64-port-handoff.md diff --git a/docs/superpowers/2026-11-13-f64-port-handoff.md b/docs/superpowers/2026-11-13-f64-port-handoff.md new file mode 100644 index 0000000..0f4e642 --- /dev/null +++ b/docs/superpowers/2026-11-13-f64-port-handoff.md @@ -0,0 +1,35 @@ +# C++ f64 CEL standard library handoff + +## Completed + +The port installs all 35 Rust f64 operations except `powi`, with structural +`sin_cos` tuples, ordinary and receiver calls, and persistent closure visibility. +The C++20 library uses cpp-library and CPM and exports `cel::std`. + +The Doxygen tutorial includes the compiled example. The reference links each +retained signature to its published CEL language-book contract. Markdown +reference input fixes navigation in both GitHub and generated Doxygen pages. + +The independent branch review identified the reference-navigation issue, now +fixed and verified against generated HTML. A separate standard-contract check +also kept NaN values outside `std::clamp`'s ordering preconditions. + +Local validation passes: 12 unit cases with 248 assertions; the complete +four-test suite, including the example and independent source/installed consumers; +Debug, Release, unspecified-build-type, and multi-config builds; clang-tidy; +AddressSanitizer and UndefinedBehaviorSanitizer; warning-clean compilation; +formatting; Doxygen warnings-as-errors; and 35 published operation anchors. + +## Deliberately excluded + +Integer overloads, f32 overloads, and `powi` are outside the approved subset. +No runtime or parser changes are needed. No review finding is deferred. +The library does not promise identical transcendental bits, NaN payloads, +preserved floating-point exception flags, or fast-math compatibility. + +## Remaining + +Publish the reviewed branch and pull request. Confirm the configured Linux, +macOS, Windows, analyzer, and documentation CI jobs at the pushed head. +Integration into `main` requires a separate user decision; do not merge +automatically. diff --git a/docs/superpowers/plans/2026-11-13-f64-port.md b/docs/superpowers/plans/2026-11-13-f64-port.md index 550623e..e8f6ed7 100644 --- a/docs/superpowers/plans/2026-11-13-f64-port.md +++ b/docs/superpowers/plans/2026-11-13-f64-port.md @@ -80,5 +80,5 @@ cel-runtime owns and executes the emitted operations. - [x] Add CI using verified build/test/documentation commands, not assumed targets. - [x] Run all unit and consumer tests, format checks, Doxygen warnings checks, and an available sanitizer configuration. Fix in-scope review findings. -- [ ] Commit the documentation and packaging, push the feature branch, and report +- [x] Commit the documentation and packaging, push the feature branch, and report the repository, branch, worktree, check results, and any material limitations.