feat: javascript helpers extension

.github/workflows/ci.yml

@@ -26,10 +26,6 @@ jobs:
     container:
       image: ubuntu:24.04
     name: Generate Test Matrix
-    # Permissions allow Danger to read PR context and post comments.
-    permissions:
-      contents: read
-      pull-requests: write
     outputs:
       matrix: ${{ steps.cpp-matrix.outputs.matrix }}
       llvm-matrix: ${{ steps.llvm-matrix.outputs.llvm-matrix }}
@@ -432,14 +428,14 @@ jobs:
         run: |
           rm -r ../third-party/llvm-project
 
-      - name: Install Duktape
+      - name: Install JerryScript
         uses: alandefreitas/cpp-actions/cmake-workflow@v1.8.12
         with:
-          source-dir: ../third-party/duktape
-          url: https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz
+          source-dir: ../third-party/jerryscript
+          url: https://github.com/jerryscript-project/jerryscript/archive/refs/tags/v3.0.0.tar.gz
           patches: |
-            ./third-party/patches/duktape/CMakeLists.txt
-            ./third-party/patches/duktape/duktapeConfig.cmake.in
+            ./third-party/patches/jerryscript/CMakeLists.txt
+            ./third-party/patches/jerryscript/jerryscriptConfig.cmake.in
           build-dir: ${sourceDir}/build
           cc: ${{ steps.setup-cpp.outputs.cc }}
           cxx: ${{ steps.setup-cpp.outputs.cxx }}
@@ -534,8 +530,8 @@ jobs:
       - name: CMake Workflow
         uses: alandefreitas/cpp-actions/cmake-workflow@v1.8.12
         env:
-          # Bump per-test timeout on Windows to avoid CTest default (1500s) killing slow golden suites.
-          CTEST_TEST_TIMEOUT: ${{ runner.os == 'Windows' && '3600' || '' }}
+          # Bump per-test timeout on Windows and for MSan jobs to avoid CTest default (1500s) killing slow golden suites.
+          CTEST_TEST_TIMEOUT: ${{ (runner.os == 'Windows' || matrix.msan == 'true') && '3600' || '' }}
         with:
           cmake-version: '>=3.26'
           cxxstd: ${{ matrix.cxxstd }}
@@ -551,7 +547,7 @@ jobs:
             -D MRDOCS_BUILD_DOCS=OFF
             -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 jerryscript_ROOT="${{ steps.rmatrix.outputs.third-party-dir }}/jerryscript/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"

.gitignore

@@ -28,4 +28,5 @@
 /.roadmap
 /AGENTS.md
 # Ignore hidden OS files under golden fixtures
-test-files/golden-tests/**/.*
+/test-files/golden-tests/**/.*
+/.code

CMakeLists.txt

@@ -277,13 +277,8 @@ llvm_map_components_to_libnames(llvm_libs all)
 string(REGEX REPLACE " /W[0-4]" "" CMAKE_C_FLAGS "${CMAKE_C_FLAGS}")
 string(REGEX REPLACE " /W[0-4]" "" CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS}")
 
-# Duktape
-find_package(duktape CONFIG)
-if (NOT DUKTAPE_FOUND)
-    # Duktape doesn't natively support CMake.
-    # Some config script patches use the capitalized version.
-    find_package(Duktape REQUIRED CONFIG)
-endif()
+# JerryScript
+find_package(jerryscript REQUIRED CONFIG)
 
 # Lua
 find_package(Lua CONFIG REQUIRED)
@@ -344,10 +339,11 @@ target_include_directories(mrdocs-core
 )
 target_include_directories(mrdocs-core
         SYSTEM PRIVATE
-        "$<BUILD_INTERFACE:${DUKTAPE_INCLUDE_DIRS}>"
-        "$<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>"
+        "$<BUILD_INTERFACE:${JERRYSCRIPT_INCLUDE_DIRS}>"
+        "$<BUILD_INTERFACE:${jerryscript_ROOT}/include>"
+        "$<BUILD_INTERFACE:/usr/local/include>"
 )
-target_link_libraries(mrdocs-core PRIVATE ${DUKTAPE_LIBRARY})
+target_link_libraries(mrdocs-core PRIVATE ${JERRYSCRIPT_LIBRARY})
 target_link_libraries(mrdocs-core PRIVATE Lua::lua)
 
 # Clang
@@ -425,8 +421,6 @@ list(APPEND TOOL_SOURCES
         ${CMAKE_CURRENT_BINARY_DIR}/src/tool/PublicToolArgs.cpp)
 
 add_executable(mrdocs ${TOOL_SOURCES})
-target_compile_definitions(mrdocs PRIVATE -DMRDOCS_TOOL)
-
 target_include_directories(mrdocs
     PUBLIC
     "$<BUILD_INTERFACE:${PROJECT_SOURCE_DIR}/include/>"

CMakePresets.json

@@ -17,8 +17,7 @@
         "CMAKE_EXPORT_COMPILE_COMMANDS": "ON",
         "LLVM_ROOT": "$env{LLVM_ROOT}",
         "Clang_ROOT": "$env{LLVM_ROOT}",
-        "duktape_ROOT": "$env{DUKTAPE_ROOT}",
-        "Duktape_ROOT": "$env{DUKTAPE_ROOT}",
+        "jerryscript_ROOT": "$env{JERRYSCRIPT_ROOT}",
         "libxml2_ROOT": "$env{LIBXML2_ROOT}",
         "LibXml2_ROOT": "$env{LIBXML2_ROOT}",
         "MRDOCS_BUILD_TESTS": "ON",

bootstrap.py

@@ -8,6 +8,18 @@
 # Official repository: https://github.com/cppalliance/mrdocs
 #
 
+# Heads up (Dec 2025): bootstrap.py is still moving toward being the single
+# setup path for ci.yml. Some presets/paths (e.g., release-msvc vs. old
+# release-windows) and edge flags may be untested. Defaults can shift while we
+# finish the move. If it blows up: 1) wipe the build dir; 2) run the matching
+# CMake/Ninja preset by hand; 3) share the failing command. This note stays
+# until Bootstrap owns the CI flow.
+
+TRANSITION_BANNER = (
+    "Heads up: bootstrap.py is mid-move to replace the process in ci.yml; presets can differ. "
+    "If it fails, try a clean build dir or run the preset yourself."
+)
+
 import argparse
 import subprocess
 import os
@@ -3404,6 +3416,7 @@ def get_command_line_args(argv=None):
 def main():
     args = get_command_line_args()
     installer = MrDocsInstaller(args)
+    installer.ui.warn(TRANSITION_BANNER)
     if installer.options.refresh_all:
         installer.refresh_all()
         exit(0)

docs/modules/ROOT/pages/contribute/codebase-tour.adoc

@@ -59,8 +59,3 @@ The documentation is written in AsciiDoc and can be built using the Antora tool.
 ==== `third-party/`—Helpers for third-party libraries
 
 This directory contains build scripts and configuration files for third-party libraries.
-
-* `third-party/`—Third-party libraries
-** `third-party/llvm/`—CMake Presets for LLVM
-** `third-party/duktape/`—CMake scripts for Duktape
-** `third-party/lua/`—A bundled Lua interpreter

docs/modules/ROOT/pages/install.adoc

@@ -80,14 +80,14 @@ Feel free to install them anywhere you want and adjust the main Mr.Docs configur
 
 [IMPORTANT]
 ====
-All instructions in this document assume you are using a CMake version above 3.26.
+All instructions in this document assume you are using a CMake version at or above 3.13 (project minimum).
 Binaries are available at https://cmake.org/download/[CMake's official website,window="_blank"].
 ====
 
-=== Duktape
+=== JerryScript
 
-Mr.Docs uses the `duktape` library for JavaScript parsing.
-From the `third-party` directory, you can download the `duktape` source code from the official release:
+Mr.Docs embeds the `JerryScript` engine for JavaScript helpers.
+From the `third-party` directory, download the 3.0.0 source archive from the official repository:
 
 [tabs]
 ====
@@ -96,95 +96,47 @@ Windows PowerShell::
 --
 [source,bash]
 ----
-Invoke-WebRequest -Uri "https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz" -OutFile "duktape-2.7.0.tar.xz" <.>
+Invoke-WebRequest -Uri "https://github.com/jerryscript-project/jerryscript/archive/refs/tags/v3.0.0.tar.gz" -OutFile "jerryscript-3.0.0.tar.gz" <.>
 ----
 
-<.> Downloads the `duktape` source code.
+<.> Downloads the `JerryScript` source code.
 --
 
 Unix Variants::
 +
 --
 [source,bash]
 ----
-curl -LJO https://github.com/svaarala/duktape/releases/download/v2.7.0/duktape-2.7.0.tar.xz <.>
+curl -LJO https://github.com/jerryscript-project/jerryscript/archive/refs/tags/v3.0.0.tar.gz <.>
 ----
 
-<.> Downloads the `duktape` source code.
+<.> Downloads the `JerryScript` source code.
 --
 ====
 
-Then patch the Duktape source code to provide CMake support.
+Patch the JerryScript source with our CMake shim and install it:
 
 [source,bash]
 ----
-tar -xf duktape-2.7.0.tar.xz <.>
-cp ../mrdocs/third-party/duktape/CMakeLists.txt ./duktape-2.7.0/CMakeLists.txt <.>
-cp ../mrdocs/third-party/duktape/duktapeConfig.cmake.in ./duktape-2.7.0/duktapeConfig.cmake.in <.>
-cd duktape-2.7.0
-----
-
-<.> Extracts the `duktape` source code.
-<.> Patches the source code with a `CMakeLists.txt` file to the `duktape-2.7.0` directory so that we can build it with CMake.
-<.> Copies the `duktapeConfig.cmake.in` file to the `duktape-2.7.0` directory so that we can install it with CMake and find it later from other CMake projects.
-
-Now adjust the `duk_config.h` file to indicate we are statically building Duktape.
+tar -xf jerryscript-3.0.0.tar.gz <.>
+cp ../mrdocs/third-party/patches/jerryscript/CMakeLists.txt ./jerryscript-3.0.0/CMakeLists.txt <.>
+cp ../mrdocs/third-party/patches/jerryscript/jerryscriptConfig.cmake.in ./jerryscript-3.0.0/jerryscriptConfig.cmake.in <.>
+cd jerryscript-3.0.0
 
-[tabs]
-====
-Windows PowerShell::
-+
---
-[source,bash]
-----
-$content = Get-Content -Path "src\duk_config.h" <.>
-$content = $content -replace '#define DUK_F_DLL_BUILD', '#undef DUK_F_DLL_BUILD' <.>
-$content | Set-Content -Path "src\duk_config.h" <.>
-----
-
-<.> Read the content of `duk_config.h`
-<.> Replace the `DUK_F_DLL_BUILD` macro with `#undef DUK_F_DLL_BUILD`
-<.> Write the content back to the file
---
-
-Unix Variants::
-+
---
-[source,bash]
-----
-sed -i 's/#define DUK_F_DLL_BUILD/#undef DUK_F_DLL_BUILD/g' "src/duk_config.h" <.>
-----
-
-<.> Disables the `DUK_F_DLL_BUILD` macro in the `duk_config.h` file to indicate we are statically building duktape.
---
-
-MacOS::
-+
---
-[source,bash]
-----
-sed -i '' 's/#define DUK_F_DLL_BUILD/#undef DUK_F_DLL_BUILD/g' src/duk_config.h <.>
-----
-
-<.> Disables the `DUK_F_DLL_BUILD` macro in the `duk_config.h` file to indicate we are statically building duktape.
---
-====
-
-And finally install the library with CMake:
-
-[source,bash]
-----
-cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release <.>
-cmake --build ./build --config Release <.>
-cmake --install ./build --prefix ./install <.>
+cmake -S . -B ./build -DCMAKE_BUILD_TYPE=Release \
+  -DJERRY_PROFILE=es.next -DJERRY_CMDLINE=OFF -DJERRY_TESTS=OFF -DJERRY_DEBUGGER=OFF \
+  -DJERRY_SNAPSHOT_SAVE=OFF -DJERRY_SNAPSHOT_EXEC=OFF \
+  -DJERRY_MEM_STATS=OFF -DJERRY_PARSER_STATS=OFF -DJERRY_LINE_INFO=OFF \
+  -DJERRY_LTO=OFF -DJERRY_LIBC=OFF -DCMAKE_MSVC_RUNTIME_LIBRARY=MultiThreadedDLL
+cmake --build ./build --config Release
+cmake --install ./build --prefix ./install
 ----
 
-<.> Configures the `duktape` library with CMake.
-<.> Builds the `duktape` library in the `build` directory.
-<.> Installs the `duktape` library with CMake support in the `install` directory.
+<.> Extracts the `JerryScript` source code.
+<.> Adds CMake packaging files maintained in this repository.
 
-The scripts above download the `duktape` source code, extract it, and configure it with CMake.
-The CMake scripts provided by MrDocs are copied to the `duktape-2.7.0` directory to facilitate the build process with CMake and provide CMake installation scripts for other projects.
+The build uses JerryScript's upstream default port implementation; no custom
+`port.c` from MrDocs is required.
 
 === Libxml2
 
@@ -317,7 +269,7 @@ cd ../..
 
 The MrDocs repository also includes a `CMakePresets.json` file that contains the parameters to configure MrDocs with CMake.
 
-To specify the installation directories, you can use the `LLVM_ROOT`, `DUKTAPE_ROOT`, and `LIBXML2_ROOT` environment variables.
+To specify the installation directories, you can use the `LLVM_ROOT`, `JERRYSCRIPT_ROOT`, and `LIBXML2_ROOT` environment variables.
 To specify a generator (`-G`) and platform name (`-A`), you can use the `CMAKE_GENERATOR` and `CMAKE_GENERATOR_PLATFORM` environment variables.
 
 You can also customize the presets by duplicating and editing the `CMakeUserPresets.json.example` file in the `mrdocs` directory.

docs/mrdocs.schema.json

@@ -7,6 +7,15 @@
       "title": "Path to the Addons directory",
       "type": "string"
     },
+    "addons-supplemental": {
+      "default": [],
+      "description": "Optional list of supplemental addons directories that are loaded after the base addons (built-in or replacement). Files in later supplemental directories override files from earlier ones and from the base addons. Use this to add or override a few templates/helpers without copying the entire addons tree.",
+      "items": {
+        "type": "string"
+      },
+      "title": "Additional addons layered on top of the base addons",
+      "type": "array"
+    },
     "auto-brief": {
       "default": true,
       "description": "When set to `true`, Mr.Docs uses the first line (until the first dot, question mark, or exclamation mark) of the comment as the brief of the symbol. When set to `false`, a explicit @brief command is required.",