Merge branch 'develop' into develop

Author: gennaroprota

.github/workflows/ci.yml

@@ -27,5 +27,7 @@
 /util/danger/node_modules/
 /.roadmap
 /AGENTS.md
+/CLAUDE.md
 # Ignore hidden OS files under golden fixtures
-test-files/golden-tests/**/.*
+/test-files/golden-tests/**/.*
+/.code

.gitignore

@@ -293,13 +293,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)
@@ -362,10 +357,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::jerry-core jerryscript::jerry-port)
 target_link_libraries(mrdocs-core PRIVATE Lua::lua)
 
 # Clang
@@ -443,8 +439,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/>"

CMakeLists.txt

@@ -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",

CMakePresets.json

@@ -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)

bootstrap.py

@@ -0,0 +1,61 @@
+#
+# Licensed under the Apache License v2.0 with LLVM Exceptions.
+# See https://llvm.org/LICENSE.txt for license information.
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+#
+# Copyright (c) 2025 Alan de Freitas (alandefreitas@gmail.com)
+#
+# Official repository: https://github.com/cppalliance/mrdocs
+#
+
+# Codecov Configuration
+# https://docs.codecov.com/docs/codecovyml-reference
+#
+# Patch Coverage Threshold Rationale
+# ==================================
+#
+# We allow a small threshold for patch coverage NOT because reduced coverage
+# is acceptable, but because some lines are inherently uncoverable and
+# produce false positives:
+#
+#   - Class declarations (e.g., `class Foo : public Bar`)
+#   - Struct declarations (e.g., `struct MyTest`)
+#   - Access specifiers (`public:`, `private:`)
+#   - Pure virtual method declarations
+#   - Opening/closing braces on their own lines
+#
+# These are not executable code - they don't generate machine instructions -
+# yet coverage tools (gcov) report them as "uncovered lines."
+#
+# Preferred Solutions (in order)
+# ------------------------------
+#
+# 1st best: Configure gcov/lcov to exclude declarations from coverage
+#           tracking entirely, so they never appear as uncovered lines.
+#           This would eliminate false positives at the source.
+#           Status: Not currently available/configured.
+#
+# 2nd best: Use an absolute threshold (e.g., "allow up to 5 uncovered lines")
+#           rather than a percentage. This would be precise and predictable.
+#           Status: Codecov only supports percentage-based thresholds.
+#
+# 3rd best: Use a percentage-based threshold (what we implement below).
+#           The threshold is set small enough that any real logic
+#           (conditionals, loops, function bodies, error paths) that isn't
+#           covered will still trigger a failure. Only trivial declaration
+#           noise should pass through.
+#
+# With typical PR sizes, a 90% patch target achieves a similar effect to
+# allowing ~5 uncovered lines in a 50-line change.
+
+coverage:
+  status:
+    # Project-wide coverage should not decrease
+    project:
+      default:
+        threshold: 1%
+
+    # Patch coverage: only applies to new/modified lines in the PR
+    patch:
+      default:
+        target: 90%

codecov.yml

@@ -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/contribute/codebase-tour.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.
 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/modules/ROOT/pages/install.adoc

@@ -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.",

docs/mrdocs.schema.json

@@ -5,6 +5,7 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
+// Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -19,6 +20,7 @@
 #include <mrdocs/Config.hpp>
 #include <mrdocs/Corpus.hpp>
 #include <mrdocs/Support/Error.hpp>
+#include <memory>
 #include <ostream>
 #include <string>
 #include <string_view>
@@ -201,11 +203,50 @@ class MRDOCS_VISIBLE
     @param outputPath The specified output path, which can be a directory or file.
     @param extension The file extension to use for single-page output.
 */
+MRDOCS_DECL
 Expected<std::string>
 getSinglePageFullPath(
     std::string_view outputPath,
     std::string_view extension);
 
+/** Install a custom generator.
+
+    This function registers a generator with the global
+    generator registry, making it available for use.
+
+    Plugins can use this function to register custom
+    generators.
+
+    @par Thread Safety
+    This function is thread-safe and may be called
+    concurrently from multiple threads.
+
+    @return An error if a generator with the same id
+    already exists.
+
+    @param G The generator to install. Ownership is
+    transferred to the registry.
+*/
+MRDOCS_DECL
+Expected<void>
+installGenerator(std::unique_ptr<Generator> G);
+
+/** Find a generator by its id.
+
+    @par Thread Safety
+    This function is thread-safe and may be called
+    concurrently from multiple threads.
+
+    @return A pointer to the generator, or `nullptr`
+    if no generator with the given id exists.
+
+    @param id The symbolic name of the generator.
+    The name must be an exact match, including case.
+*/
+MRDOCS_DECL
+Generator const*
+findGenerator(std::string_view id) noexcept;
+
 } // mrdocs