updates

.github/workflows/ci.yaml

@@ -17,17 +17,26 @@ jobs:
           - {
               name: "Ubuntu GCC 13",
               os: ubuntu-latest,
-              cxx: g++-13
+              cxx: g++-13,
+              preset: gcc
             }
           - {
               name: "Ubuntu Clang 18",
               os: ubuntu-latest,
-              cxx: clang++-18
+              cxx: clang++-18,
+              preset: clang
+            }
+          - {
+              name: "Ubuntu Clang 18 (ASan+UBSan)",
+              os: ubuntu-latest,
+              cxx: clang++-18,
+              preset: asan-ubsan
             }
           - {
               name: "Windows MSVC",
               os: windows-latest,
-              cxx: cl
+              cxx: cl,
+              preset: msvc
             }
 
     steps:
@@ -48,18 +57,48 @@ jobs:
 
     - name: Configure CMake
       run: |
-        if [ "${{ matrix.config.os }}" = "windows-latest" ]; then
-          cmake -B build -DSOATABLE_BUILD_TESTS=ON -DSOATABLE_BUILD_EXAMPLES=ON
+        if [ "${{ runner.os }}" = "Windows" ]; then
+          cmake --preset ${{ matrix.config.preset }}
         else
-          cmake -B build -DSOATABLE_BUILD_TESTS=ON -DSOATABLE_BUILD_EXAMPLES=ON -DCMAKE_CXX_COMPILER=${{ matrix.config.cxx }}
+          cmake --preset ${{ matrix.config.preset }} -DCMAKE_CXX_COMPILER=${{ matrix.config.cxx }}
         fi
       shell: bash
 
     - name: Build
-      run: cmake --build build --config Release
+      run: cmake --build --preset ${{ matrix.config.preset }}
+      shell: bash
 
     - name: Run Tests
       run: |
-        cd build
-        ctest -C Release --output-on-failure
+        # Treat any sanitizer finding as a hard failure.
+        export ASAN_OPTIONS=halt_on_error=1:abort_on_error=1
+        export UBSAN_OPTIONS=halt_on_error=1:print_stacktrace=1
+        ctest --preset ${{ matrix.config.preset }}
       shell: bash
+
+  amalgamation:
+    name: Amalgamated single-header compiles
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install GCC 13
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y g++-13
+
+    - name: Generate and compile the amalgamated headers
+      shell: bash
+      run: |
+        set -euo pipefail
+
+        # Core only, and the full bundle with every opt-in add-on inlined.
+        python3 scripts/amalgamate.py --output dist/soatable_core.hpp
+        python3 scripts/amalgamate.py --with all --output dist/soatable_full.hpp
+
+        # Each generated header must compile as a standalone translation unit.
+        for hdr in dist/soatable_core.hpp dist/soatable_full.hpp; do
+          printf '#include "%s"\nint main() { return 0; }\n' "$hdr" > tu.cpp
+          g++-13 -std=c++23 -Wall -Wextra -c tu.cpp -o tu.o
+          echo "OK: ${hdr} compiles as a single header"
+        done

.github/workflows/docs.yaml

@@ -0,0 +1,45 @@
+name: Docs
+
+on:
+  push:
+    branches: [ main ]
+
+# Allow one concurrent deployment.
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+    - uses: actions/checkout@v4
+
+    - name: Install Doxygen
+      run: sudo apt-get update && sudo apt-get install -y doxygen
+
+    - name: Generate API documentation
+      run: |
+        cmake -S . -B build-docs \
+          -DSOATABLE_BUILD_DOCUMENTATION=ON \
+          -DSOATABLE_BUILD_TESTS=OFF \
+          -DSOATABLE_BUILD_EXAMPLES=OFF \
+          -DSOATABLE_BUILD_BENCHMARKS=OFF
+        cmake --build build-docs --target docs
+
+    - name: Upload Pages artifact
+      uses: actions/upload-pages-artifact@v3
+      with:
+        path: build-docs/doxygen/html
+
+    - name: Deploy to GitHub Pages
+      id: deployment
+      uses: actions/deploy-pages@v4

.gitignore

@@ -1,8 +1,16 @@
 .venv/
 .env
 build/
+build-docs/
 install/
 .cache/
 CMakeUserPresets.json
 *-workspace
 /.vscode/*.json
+prompts.txt
+# Generated artifacts
+dist/
+bench/
+
+__pycache__
+*.pyc

CLAUDE.md

@@ -0,0 +1,89 @@
+# Modern C++ Best Practices
+
+## Language & Compiler
+
+- Target C++17 minimum; prefer C++20/23. Set `CMAKE_CXX_STANDARD` explicitly; disable extensions (`-pedantic`).
+- Enable `-Wall -Wextra -Wconversion -Wsign-conversion` and treat warnings as errors (`-Werror`).
+
+## Style & Naming
+
+- `m_` prefix for private members; `snake_case` for variables/functions; `PascalCase` for types; `SCREAMING_SNAKE_CASE` for macros and Constants.
+- All symbols (variable, parameters, functions) must be at least 3 characters long.
+- Alwayse Use `std::print`/`std::println`/`std::format` for output.
+- No magic literals, replace with named `constexpr` values. Declare variables close to first use.
+- Keep functions short and flat; remove unused variables, parameters, and includes.
+- Use `#pragma once`; keep headers to declarations and inline/template definitions only.
+- Do not use mdash (`--`) in code, comments, or documentation.
+
+## Variables & Types
+
+- Always initialize variables at declaration; prefer brace initialization `T x{value}` to prevent narrowing.
+- Use `auto` when type is obvious; `const` by default; `constexpr` for compile-time constants.
+- Avoid `using namespace std` in headers. Use `enum class`; use `std::string_view` for read-only strings.
+- Never mix signed/unsigned arithmetic; never use C-style casts, use `static_cast`, `dynamic_cast`, etc.
+- Never use raw pointers for ownership; use references or smart pointers instead. Avoid `void*` and `reinterpret_cast`.
+- Never use `goto` or `longjmp`; prefer structured control flow and RAII for cleanup.
+- Never use C-style arrays or C-style strings; prefer `std::array`, `std::vector`, and `std::string` for safety and convenience.
+
+## Memory Management
+
+- Follow RAII: tie every resource (memory, file, mutex) to an object's lifetime.
+- Use `std::unique_ptr`/`std::shared_ptr`/`std::weak_ptr` via `make_unique`/`make_shared`, never `new`/`delete` directly.
+- Follow Rule of Zero (all RAII members) or Rule of Five (when owning a raw resource).
+- Detect leaks with AddressSanitizer; use standard containers over raw arrays.
+
+## Functions & Classes
+
+- One logical operation per function; always use trailing return types.
+- Pass non-trivial types as `const T&`; return by value (rely on NRVO/RVO).
+- Mark `[[nodiscard]]` where return values must not be ignored; mark `noexcept` when applicable.
+- Single-argument constructors must be `explicit`; keep members `private`; use `override`/`final` on overrides.
+- Prefer composition over inheritance; declare base destructors `virtual` (or `protected` non-virtual).
+- Do not call virtual functions from constructors or destructors.
+
+## Error Handling
+
+- Use exceptions for errors (not for normal control flow); catch by `const` reference to avoid slicing.
+- Maintain a consistent exception-safety guarantee: basic, strong, or no-throw.
+- Use `static_assert` for compile-time invariants; `assert()` for debug-only preconditions, never on user input.
+- Consider `std::expected<T, E>` (C++23) for predictable, performance-sensitive failure paths.
+
+## Templates & Concurrency
+
+- Constrain templates with C++20 concepts; use `if constexpr` over SFINAE/`enable_if`.
+- Use variadic templates and fold expressions instead of recursive specializations.
+- Protect shared mutable state with `std::mutex`; prefer `std::jthread` over `std::thread`.
+- Use `std::atomic<T>` for lock-free single-variable operations; never `volatile` for inter-thread communication.
+- Minimize lock duration; avoid callbacks or virtual calls while holding a lock; prefer `std::async` and parallel algorithms.
+
+## Performance & Build
+
+- Profile before optimizing; prefer `std::vector` for cache-friendly access; use `reserve()` when size is known.
+- Use move semantics to avoid deep copies; prefer standard algorithms (`std::sort`, `std::transform`) over hand-written loops.
+- Use CMake (≥ 3.25) with target-centric paradigm: `target_include_directories`, `target_compile_options`, `target_link_libraries`.
+- Use `FetchContent` or vcpkg/Conan for dependencies; use out-of-source builds and CMake Presets.
+- Enable `CMAKE_EXPORT_COMPILE_COMMANDS=ON` for tooling; use `ccache`/`sccache` to speed up rebuilds.
+
+## Testing & Tooling
+
+- Use GoogleTest/Catch2 with CTest; write tests before or alongside implementation.
+- Run tests under AddressSanitizer and UndefinedBehaviourSanitizer; use fuzz testing for parsers and untrusted input.
+- Enforce clang-format in CI; use clang-tidy with `cppcoreguidelines-*`, `modernize-*`, `readability-*` checks.
+- Use debuggers (GDB, LLDB) actively rather than `std::cout`; use `compile_commands.json` for accurate tooling.
+- Use real implementations; only mock external dependencies (LLM APIs, cloud services).
+- Test public interface behavior, not implementation details, keeps tests resilient to refactoring.
+- Tests must be fast, isolated, and have descriptive names; cover edge cases and error conditions.
+- Location: `tests/unittests/` following source structure.
+
+## CI/CD & Maintenance
+
+## Versioning & Breaking Changes
+
+- Follow Semantic Versioning 2.0.0 (`MAJOR.MINOR.PATCH`).
+- A breaking change is any backward-incompatible modification to the public API, including data schemas, CLI, and server communication formats.
+- CI must build and test before merging; build across GCC, Clang, and MSVC.
+- Document the _why_, not the _what_; use Doxygen (`///`) for API docs and `//` for implementation notes.
+- Keep public API surface minimal; mark deprecated APIs with `[[deprecated("reason")]]` and include a migration path.
+- Follow the Boy Scout Rule; track technical debt explicitly; maintain a `CHANGELOG.md` and `CONTRIBUTING.md`.
+
+---

CMakeLists.txt

@@ -1,18 +1,32 @@
-cmake_minimum_required(VERSION 3.20)
+cmake_minimum_required(VERSION 3.25)
 
-project(soatable VERSION 0.1.0 LANGUAGES CXX)
+file(READ "VERSION.txt" RAW_VERSION)
+string(STRIP "${RAW_VERSION}" APP_VERSION)
+project(SOATABLE VERSION ${APP_VERSION} LANGUAGES CXX)
 
-set(CMAKE_EXPORT_COMPILE_COMMANDS ON) 
+set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 
 set(FETCHCONTENT_BASE_DIR "${CMAKE_SOURCE_DIR}/.cache/_deps")
+include(${CMAKE_SOURCE_DIR}/cmake/Helpers.cmake)
+include(${CMAKE_SOURCE_DIR}/cmake/Versions.cmake)
 
-include(GNUInstallDirs)
-include(CMakePackageConfigHelpers)
+if(${PROJECT_NAME}_ADD_COVERAGE_ANALYSIS)
+    add_coverage_analysis(${CMAKE_SOURCE_DIR})
+endif()
 
-option(SOATABLE_BUILD_EXAMPLES "Build the SoaTable example program" ON)
-option(SOATABLE_BUILD_BENCHMARKS "Build the SoaTable benchmark program" ON)
-option(SOATABLE_BUILD_TESTS "Build the SoaTable tests" ON)
+if(${PROJECT_NAME}_APPLY_FORMATING)
+    apply_formating(${PROJECT_NAME}_USE_PER_FILE_FORMATTING ${CMAKE_SOURCE_DIR}/include)
+    apply_formating(${PROJECT_NAME}_USE_PER_FILE_FORMATTING ${CMAKE_SOURCE_DIR}/example)
+    apply_formating(${PROJECT_NAME}_USE_PER_FILE_FORMATTING ${CMAKE_SOURCE_DIR}/benchmarks)
+    apply_formating(${PROJECT_NAME}_USE_PER_FILE_FORMATTING ${CMAKE_SOURCE_DIR}/tests)
+endif()
 
+if(${PROJECT_NAME}_APPLY_CLANG_TIDY_GLOBALY)
+    apply_clang_tidy_globaly()
+endif()
+
+include(GNUInstallDirs)
+include(CMakePackageConfigHelpers)
 
 add_library(soatable INTERFACE)
 add_library(soatable::soatable ALIAS soatable)
@@ -23,8 +37,19 @@ target_include_directories(soatable INTERFACE
   $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
 )
 
+# Propagate the MSVC debugger visualizer to consumers.
+target_sources(soatable INTERFACE
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/tools/visualizers/soatable.natvis>
+  $<INSTALL_INTERFACE:${CMAKE_INSTALL_DATADIR}/soatable/visualizers/soatable.natvis>
+)
+
 install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
 
+# Ship the debugger visualizers (MSVC .natvis and GDB pretty-printers) alongside the package.
+install(DIRECTORY tools/visualizers/ DESTINATION ${CMAKE_INSTALL_DATADIR}/soatable/visualizers
+  PATTERN "__pycache__" EXCLUDE
+)
+
 install(TARGETS soatable
   EXPORT soatableTargets
 )
@@ -53,15 +78,19 @@ install(FILES
   DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/soatable
 )
 
-if(SOATABLE_BUILD_EXAMPLES AND EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/example)
+if(SOATABLE_BUILD_EXAMPLES AND EXISTS ${CMAKE_SOURCE_DIR}/example)
   add_subdirectory(example)
 endif()
 
-if(SOATABLE_BUILD_BENCHMARKS AND EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/benchmarks)
+if(SOATABLE_BUILD_BENCHMARKS AND EXISTS ${CMAKE_SOURCE_DIR}/benchmarks)
   add_subdirectory(benchmarks)
 endif()
 
-if(SOATABLE_BUILD_TESTS AND EXISTS ${CMAKE_CURRENT_SOURCE_DIR}/tests)
+if(SOATABLE_BUILD_TESTS AND EXISTS ${CMAKE_SOURCE_DIR}/tests)
   enable_testing()
   add_subdirectory(tests)
 endif()
+
+if(SOATABLE_BUILD_DOCUMENTATION)
+  build_documenation()
+endif()