Metadata library: safety refactors and fixes

.clang-format

@@ -0,0 +1,229 @@
+#
+# Copyright (c) 2023 Alan de Freitas ([email protected])
+#
+# Distributed under the Boost Software License, Version 1.0.
+# See accompanying file LICENSE or copy at http://www.boost.org/LICENSE_1_0.txt
+#
+
+# ---------------------------------------------------------------------------
+# MrDocs Formatting Guidelines (Clang-Format Reference)
+#
+# This file encodes the formatting style we generally follow in MrDocs,
+# based on conventions we have been using in Boost projects.
+#
+# Important:
+# - Do not run clang-format across entire files or the whole project.
+# - This configuration is provided as a *reference* to help new contributors
+#   understand the style rules and configure their editors/IDEs.
+# - You may use clang-format to format only the *new code you add or modify*
+#   in a commit. Never reformat unrelated code.
+#
+# The goal is to keep the codebase consistent and allow new contributors
+# to follow the same style, while minimizing churn and noise, and
+# without introducing large, style-only changes in version history.
+#
+# If in doubt, look at the surrounding code in the file and follow its style.
+# This file is here to make that easier, not to replace careful review.
+# ---------------------------------------------------------------------------
+
+Language: Cpp
+Standard: Latest
+BasedOnStyle: Microsoft
+
+# Columns and Lines
+ColumnLimit: 80
+ReflowComments: Always
+TabWidth: 8
+UseCRLF: false
+UseTab: Never
+DeriveLineEnding: true
+
+# Breaking around braces
+InsertBraces: true
+BreakBeforeBraces: Custom
+BraceWrapping:
+  # Control
+  AfterControlStatement: Always
+  AfterCaseLabel: true
+  BeforeCatch: true
+  BeforeElse: true
+  BeforeWhile: true
+  # Definition
+  AfterNamespace: false
+  AfterStruct: false
+  AfterClass: false
+  SplitEmptyRecord: false
+  AfterFunction: true
+  SplitEmptyFunction: false
+  BeforeLambdaBody: false
+  AfterEnum: false
+  SplitEmptyNamespace: true
+  AfterUnion: false
+  AfterExternBlock: true
+  # Extra
+  IndentBraces: false
+
+# Breaking around specifiers
+#     Namespaces
+CompactNamespaces: false
+#     Templates
+AlwaysBreakTemplateDeclarations: Yes
+BreakBeforeConceptDeclarations: true
+#     Classes
+BreakInheritanceList: BeforeComma
+EmptyLineAfterAccessModifier: Never
+EmptyLineBeforeAccessModifier: Leave
+#     Functions
+AlwaysBreakAfterDefinitionReturnType: All
+AlwaysBreakAfterReturnType: All
+MaxEmptyLinesToKeep: 2
+#     Strings
+AlwaysBreakBeforeMultilineStrings: false
+BreakStringLiterals: true
+#     Expressions
+BreakConstructorInitializers: BeforeComma
+BreakBeforeBinaryOperators: All
+BreakBeforeTernaryOperators: false
+
+# Breaking single line blocks
+#     Control
+AllowShortBlocksOnASingleLine: Never
+AllowShortCaseLabelsOnASingleLine: false
+AllowShortIfStatementsOnASingleLine: Never
+AllowShortLoopsOnASingleLine: false
+#     Declarations
+AllowShortEnumsOnASingleLine: false
+#     Function
+AllowAllParametersOfDeclarationOnNextLine: false
+AllowShortFunctionsOnASingleLine: Empty
+AllowShortLambdasOnASingleLine: Inline
+#     Expressions
+AllowAllArgumentsOnNextLine: false
+
+# Indentation
+#    Parameters
+IndentWidth: 4
+#    Definitions
+NamespaceIndentation: None
+IndentExternBlock: NoIndent
+IndentPPDirectives: AfterHash
+#    Classes
+AccessModifierOffset: -4
+IndentAccessModifiers: false
+#    Templates
+IndentRequires: false
+#    Functions
+IndentWrappedFunctionNames: false
+LambdaBodyIndentation: OuterScope
+#    Control
+ConstructorInitializerIndentWidth: 4
+IndentCaseBlocks: false
+IndentCaseLabels: false
+IndentGotoLabels: true
+#    Expressions
+ContinuationIndentWidth: 4
+InsertTrailingCommas: None
+KeepEmptyLinesAtTheStartOfBlocks: false
+
+# Alignment
+#    Macros
+AlignConsecutiveMacros: Consecutive
+AttributeMacros: [ 'FUTURES_CONSTEXPR', 'FUTURES_NODISCARD' ]
+IfMacros: [ 'FUTURES_IF_CONSTEXPR', 'SECTION', 'TEST_CASE' ]
+TypenameMacros: [ 'FUTURES_DETAIL' ]
+#    Declaration
+PointerAlignment: Left
+ReferenceAlignment: Pointer
+DerivePointerAlignment: true
+AlignConsecutiveDeclarations: None
+QualifierAlignment: Custom
+QualifierOrder: [ 'inline', 'static', 'constexpr', 'type', 'const' ]
+#    Namespace
+ShortNamespaceLines: 0
+#    Brackets
+AlignAfterOpenBracket: AlwaysBreak
+#    Expressions
+AlignArrayOfStructures: Right
+AlignConsecutiveAssignments: None
+AlignConsecutiveBitFields: None
+AlignEscapedNewlines: Left
+AlignOperands: Align
+AlignTrailingComments: true
+
+# Spaces
+SpaceAfterCStyleCast: true
+SpaceAfterLogicalNot: false
+SpaceAfterTemplateKeyword: true
+SpaceAroundPointerQualifiers: Default
+SpaceBeforeAssignmentOperators: true
+SpaceBeforeCaseColon: false
+SpaceBeforeCpp11BracedList: false
+SpaceBeforeCtorInitializerColon: true
+SpaceBeforeInheritanceColon: true
+SpaceBeforeParens: ControlStatements
+SpaceBeforeRangeBasedForLoopColon: false
+SpacesInSquareBrackets: false
+SpaceBeforeSquareBrackets: false
+SpacesBeforeTrailingComments: 1
+SpaceInEmptyBlock: false
+SpaceInEmptyParentheses: false
+SpacesInAngles: Never
+SpacesInCStyleCastParentheses: false
+SpacesInConditionalStatement: false
+SpacesInParentheses: false
+Cpp11BracedListStyle: false
+
+# BinPack
+BinPackArguments: false
+BinPackParameters: false
+BitFieldColonSpacing: After
+ExperimentalAutoDetectBinPacking: true
+PackConstructorInitializers: CurrentLine
+
+# Penalties
+PenaltyBreakAssignment: 512
+PenaltyBreakBeforeFirstCallParameter: 512
+PenaltyBreakComment: 512
+PenaltyBreakFirstLessLess: 512
+PenaltyBreakString: 512
+PenaltyBreakTemplateDeclaration: 512
+PenaltyExcessCharacter: 256
+PenaltyIndentedWhitespace: 8
+PenaltyReturnTypeOnItsOwnLine: 2
+
+# Sorting
+SortIncludes: CaseInsensitive
+SortUsingDeclarations: true
+IncludeBlocks: Merge
+IncludeCategories:
+  - Regex: '^<mrdocs/Platform\.hpp>$'            # always first
+    Priority: 0
+  - Regex: '^".*"'                               # quoted includes come next
+    Priority: 1
+  - Regex: '^<lib/.*>'                           # internal project headers
+    Priority: 2
+  - Regex: '^<mrdocs/.*>'                        # internal project headers
+    Priority: 3
+  - Regex: '^<test_suite/.*>'                    # test suite headers
+    Priority: 4
+  - Regex: '^<clang/.*>'                         # clang headers
+    Priority: 5
+  - Regex: '^<llvm/.*>'                          # llvm headers
+    Priority: 6
+  - Regex: '^<fmt/.*>'                           # fmt headers
+    Priority: 7
+  - Regex: '^<duktape/.*>'                       # duktape headers
+    Priority: 8
+    # Lua headers
+  - Regex: '^<lua.*>'                           # Lua headers
+    Priority: 9
+  - Regex: '^<(?!mrdocs/|clang/|llvm/|test_suite/|fmt/|duktape/)[^/]+/.*>' # other angle-bracket includes
+    Priority: 10
+  - Regex: '^<[^/]+>'                            # C++ standard headers like <vector>
+    Priority: 11
+  - Regex: '.*'                                  # fallback
+    Priority: 12
+
+# Comments
+FixNamespaceComments: true
+CommentPragmas: '^ clang-format'

.github/workflows/ci.yml

@@ -402,6 +402,26 @@ jobs:
           run-tests: false
           trace-commands: true
 
+      - name: Install Lua
+        uses: alandefreitas/cpp-actions/[email protected]
+        with:
+          source-dir: ../third-party/lua
+          url: https://github.com/lua/lua/archive/refs/tags/v5.4.8.tar.gz
+          patches: |
+            ./third-party/lua/CMakeLists.txt
+            ./third-party/lua/LuaConfig.cmake.in
+          build-dir: ${sourceDir}/build
+          cc: ${{ steps.setup-cpp.outputs.cc }}
+          cxx: ${{ steps.setup-cpp.outputs.cxx }}
+          ccflags: ${{ matrix.common-ccflags }}
+          cxxflags: ${{ steps.rmatrix.outputs.common-cxxflags }}
+          build-type: ${{ matrix.build-type }}
+          shared: false
+          install: true
+          install-prefix: ${sourceDir}/install
+          run-tests: false
+          trace-commands: true
+
       - name: Install Libxml2
         uses: alandefreitas/cpp-actions/[email protected]
         if: matrix.compiler == 'msvc'
@@ -479,6 +499,9 @@ jobs:
             -D CMAKE_EXE_LINKER_FLAGS="${{ steps.rmatrix.outputs.common-ldflags }}"
             -D LLVM_ROOT="${{ steps.rmatrix.outputs.llvm-path }}"
             -D duktape_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/duktape/install"
+            -D LUA_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
+            -D Lua_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
+            -D lua_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/lua/install"
             ${{ runner.os == 'Windows' && '-D LibXml2_ROOT=../third-party/libxml2/install' || '' }}
           export-compile-commands: true
           run-tests: true
@@ -497,6 +520,71 @@ jobs:
           # The schema in the docs folder is valid
           npx -y -p ajv-cli -- ajv compile -s docs/mrdocs.schema.json
 
+      - name: Verify snippet .cpp files match golden tests (bash)
+        shell: bash
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+
+          SRC="docs/website/snippets"
+          DST="test-files/golden-tests/snippets"
+
+          [[ -d "$SRC" ]] || { echo "Source directory not found: $SRC"; exit 2; }
+          [[ -d "$DST" ]] || { echo "Destination directory not found: $DST"; exit 2; }
+
+          missing=()
+          mismatched=()
+
+          # Walk all .cpp files under SRC
+          while IFS= read -r -d '' src; do
+            rel="${src#$SRC/}"
+            dst="$DST/$rel"
+
+            if [[ ! -f "$dst" ]]; then
+              missing+=("$rel")
+              continue
+            fi
+
+            if [[ "${STRICT_EOL:-0}" == "1" ]]; then
+              # strict byte-for-byte comparison
+              if ! cmp -s -- "$src" "$dst"; then
+                mismatched+=("$rel")
+              fi
+            else
+              # ignore CRLF/LF differences using git diff (available on all runners)
+              if ! git diff --no-index --ignore-cr-at-eol --quiet -- "$src" "$dst"; then
+                mismatched+=("$rel")
+              fi
+            fi
+          done < <(find "$SRC" -type f -name '*.cpp' -print0)
+
+          if (( ${#missing[@]} || ${#mismatched[@]} )); then
+            if (( ${#missing[@]} )); then
+              echo "Missing corresponding golden files:"
+              printf '  %s\n' "${missing[@]}"
+            fi
+            if (( ${#mismatched[@]} )); then
+              echo "Content mismatches:"
+              printf '  %s\n' "${mismatched[@]}"
+            fi
+            exit 1
+          fi
+
+          echo "All snippet .cpp files are present and match."
+        env:
+          # Set to "1" to enforce byte-for-byte equality (do not ignore CRLF/LF)
+          STRICT_EOL: "0"
+
+
+      - name: Check landing page snippets
+        run: |
+          # Find python
+          python=$(command -v python3 || command -v python)
+          # The schema in this branch is up to date 
+          "$python" ./util/generate-yaml-schema.py --check
+          # The schema in the docs folder is valid
+          npx -y -p ajv-cli -- ajv compile -s docs/mrdocs.schema.json
+
       - name: Upload GitHub Release Artifacts
         if: ${{ matrix.is-main && matrix.compiler != 'clang' }}
         uses: actions/upload-artifact@v4

.gitignore

@@ -20,6 +20,5 @@
 /share/mrdocs/libcxx/
 /share/mrdocs/clang/
 /docs/modules/reference
-/.clang-format
 /.gdbinit
 /.lldbinit

CMakeLists.txt

@@ -284,6 +284,9 @@ if (NOT DUKTAPE_FOUND)
     find_package(Duktape REQUIRED CONFIG)
 endif()
 
+# Lua
+find_package(Lua CONFIG REQUIRED)
+
 unset(CMAKE_FOLDER)
 
 #-------------------------------------------------
@@ -321,7 +324,8 @@ target_include_directories(mrdocs-core
     "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
     PRIVATE
     "${PROJECT_SOURCE_DIR}/src"
-    "${PROJECT_BINARY_DIR}/src")
+    "${PROJECT_BINARY_DIR}/src"
+)
 target_compile_definitions(
     mrdocs-core
     PUBLIC
@@ -343,6 +347,7 @@ target_include_directories(mrdocs-core
         "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
 )
 target_link_libraries(mrdocs-core PRIVATE ${DUKTAPE_LIBRARY})
+target_link_libraries(mrdocs-core PRIVATE Lua::lua)
 
 # Clang
 if (CLANG_SIMPLE_LIBS)