build(jerryscript): improve tests

Author: alandefreitas

CMakeLists.txt

@@ -343,14 +343,7 @@ target_include_directories(mrdocs-core
         "$<BUILD_INTERFACE:${jerryscript_ROOT}/include>"
         "$<BUILD_INTERFACE:/usr/local/include>"
 )
-# JerryScript: Link jerry-core and jerry-port.
-# When JERRY_EXTERNAL_CONTEXT=ON, jerry-port is built WITHOUT jerry-port-context.c,
-# so mrdocs-core provides the only implementations of jerry_port_context_* functions.
-# This avoids ODR violations and makes the design explicit.
-target_link_libraries(mrdocs-core PRIVATE jerryscript::jerry-core)
-if(TARGET jerryscript::jerry-port)
-    target_link_libraries(mrdocs-core PRIVATE jerryscript::jerry-port)
-endif()
+target_link_libraries(mrdocs-core PRIVATE jerryscript::jerry-core jerryscript::jerry-port)
 target_link_libraries(mrdocs-core PRIVATE Lua::lua)
 
 # Clang

include/mrdocs/Support/JavaScript.hpp

@@ -83,11 +83,12 @@ class Handlebars;
     - `jerry_port_context_free`: Frees context memory
     - `jerry_port_context_get`: Returns current thread's active context
 
-    The default jerry-port uses a static global pointer, limiting all threads
-    to a single shared context. Our TLS-based implementations allow each
-    thread to have its own active context, enabling parallel JavaScript
-    execution. Our symbols are linked before jerry-port so they take
-    precedence during symbol resolution.
+    The default jerry-port context functions use a static global pointer,
+    limiting all threads to a single shared context. When building with
+    JERRY_EXTERNAL_CONTEXT=ON, these functions are excluded from jerry-port
+    (see third-party/patches/jerryscript/CMakeLists.txt), and mrdocs provides
+    TLS-based implementations that allow each thread to have its own active
+    context, enabling parallel JavaScript execution.
 */
 namespace js {
 

src/lib/Gen/hbs/AddonPaths.hpp

@@ -3,18 +3,35 @@
 // See https://llvm.org/LICENSE.txt for license information.
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
-// Internal helper for Handlebars addon search paths.
+// Copyright (c) 2025 Alan de Freitas ([email protected])
+//
+// Official repository: https://github.com/cppalliance/mrdocs
 //
 
 #ifndef MRDOCS_LIB_GEN_HBS_ADDONPATHS_HPP
 #define MRDOCS_LIB_GEN_HBS_ADDONPATHS_HPP
 
 #include <lib/ConfigImpl.hpp>
 #include <mrdocs/Support/Path.hpp>
+#include <optional>
+#include <string>
+#include <string_view>
 #include <vector>
 
 namespace mrdocs::hbs::addon_paths {
 
+/** Returns the list of addon root directories from the configuration.
+
+    This function collects all valid addon root paths by checking
+    the primary addons directory and any supplemental addon directories
+    specified in the configuration.
+
+    @param config The configuration containing addon path settings.
+    @return A vector of existing addon root directory paths. The primary
+            addons directory (if it exists) appears first, followed by
+            any existing supplemental addon directories in their
+            configured order.
+*/
 inline std::vector<std::string>
 addonRoots(Config const& config)
 {
@@ -32,6 +49,128 @@ addonRoots(Config const& config)
     return roots;
 }
 
+/** Returns directories containing Handlebars partial templates.
+
+    For each addon root, this function looks for partial templates in:
+    1. `generator/common/partials/` - shared partials for all formats
+    2. `generator/<ext>/partials/` - format-specific partials
+
+    The order preserves root precedence: for each root, common partials
+    are loaded first, then format-specific ones. Later roots (supplemental
+    addons) can override partials from earlier roots.
+
+    @param roots The addon root directories to search.
+    @param ext The output format extension (e.g., "html", "adoc").
+    @return A vector of existing partial directories in load order.
+*/
+inline std::vector<std::string>
+partialDirs(std::vector<std::string> const& roots, std::string_view ext)
+{
+    std::vector<std::string> dirs;
+    dirs.reserve(roots.size() * 2);
+
+    for (auto const& root : roots)
+    {
+        auto const commonDir = files::appendPath(root, "generator", "common", "partials");
+        if (files::exists(commonDir))
+            dirs.push_back(commonDir);
+
+        auto const formatDir = files::appendPath(root, "generator", ext, "partials");
+        if (files::exists(formatDir))
+            dirs.push_back(formatDir);
+    }
+
+    return dirs;
+}
+
+/** Returns directories containing JavaScript helper scripts.
+
+    For each addon root, this function looks for helper scripts in:
+    1. `generator/common/helpers/` - shared helpers for all formats
+    2. `generator/<ext>/helpers/` - format-specific helpers
+
+    The order preserves root precedence: for each root, common helpers
+    are loaded first, then format-specific ones. Later roots (supplemental
+    addons) can override helpers from earlier roots.
+
+    @param roots The addon root directories to search.
+    @param ext The output format extension (e.g., "html", "adoc").
+    @return A vector of existing helper directories in load order.
+*/
+inline std::vector<std::string>
+helperDirs(std::vector<std::string> const& roots, std::string_view ext)
+{
+    std::vector<std::string> dirs;
+    dirs.reserve(roots.size() * 2);
+
+    for (auto const& root : roots)
+    {
+        auto const commonDir = files::appendPath(root, "generator", "common", "helpers");
+        if (files::exists(commonDir))
+            dirs.push_back(commonDir);
+
+        auto const formatDir = files::appendPath(root, "generator", ext, "helpers");
+        if (files::exists(formatDir))
+            dirs.push_back(formatDir);
+    }
+    return dirs;
+}
+
+/** Returns directories containing layout templates.
+
+    For each addon root, this function looks for layout templates in:
+    `generator/<ext>/layouts/`
+
+    Layout templates define the overall page structure (e.g., wrapper.html.hbs,
+    index.html.hbs). Later roots can override layouts from earlier roots.
+
+    @param roots The addon root directories to search.
+    @param ext The output format extension (e.g., "html", "adoc").
+    @return A vector of existing layout directories in load order.
+*/
+inline std::vector<std::string>
+layoutDirs(std::vector<std::string> const& roots, std::string_view ext)
+{
+    std::vector<std::string> dirs;
+    dirs.reserve(roots.size());
+    for (auto const& root : roots)
+    {
+        auto const dir = files::appendPath(root, "generator", ext, "layouts");
+        if (files::exists(dir))
+            dirs.push_back(dir);
+    }
+    return dirs;
+}
+
+/** Searches addon directories for a specific file.
+
+    Searches through addon roots in reverse order (supplemental addons
+    first) to find the specified file. This allows supplemental addons
+    to override files from the primary addon directory.
+
+    @param config The configuration containing addon paths.
+    @param generator The generator subdirectory (e.g., "html", "common").
+    @param subdir The subdirectory within the generator (e.g., "layouts").
+    @param filename The filename to search for.
+    @return The full path to the file if found, or std::nullopt.
+*/
+inline std::optional<std::string>
+findFile(
+    Config const& config,
+    std::string_view generator,
+    std::string_view subdir,
+    std::string_view filename)
+{
+    auto roots = addonRoots(config);
+    for (auto it = roots.rbegin(); it != roots.rend(); ++it)
+    {
+        std::string candidate = files::appendPath(*it, "generator", generator, subdir, filename);
+        if (files::exists(candidate))
+            return candidate;
+    }
+    return std::nullopt;
+}
+
 } // namespace mrdocs::hbs::addon_paths
 
 #endif // MRDOCS_LIB_GEN_HBS_ADDONPATHS_HPP

src/lib/Gen/hbs/Builder.cpp

@@ -28,63 +28,17 @@ namespace hbs {
 
 namespace {
 
-std::vector<std::string>
-makePartialDirs(std::vector<std::string> const& roots, std::string_view ext)
-{
-    std::vector<std::string> dirs;
-    dirs.reserve(roots.size() * 2);
-
-    // Preserve root precedence: for each root load common first, then format.
-    // Later roots (supplemental addons) still override earlier ones.
-    for (auto const& root : roots)
-    {
-        auto const commonDir = files::appendPath(root, "generator", "common", "partials");
-        if (files::exists(commonDir))
-            dirs.push_back(commonDir);
-
-        auto const formatDir = files::appendPath(root, "generator", ext, "partials");
-        if (files::exists(formatDir))
-            dirs.push_back(formatDir);
-    }
-
-    return dirs;
-}
+/** Loads Handlebars partial templates from a directory.
 
-std::vector<std::string>
-makeHelperDirs(std::vector<std::string> const& roots, std::string_view ext)
-{
-    std::vector<std::string> dirs;
-    dirs.reserve(roots.size() * 2);
-
-    // Preserve root precedence: for each root load common first, then format.
-    // Later roots (supplemental addons) still override earlier ones.
-    for (auto const& root : roots)
-    {
-        auto const commonDir = files::appendPath(root, "generator", "common", "helpers");
-        if (files::exists(commonDir))
-            dirs.push_back(commonDir);
-
-        auto const formatDir = files::appendPath(root, "generator", ext, "helpers");
-        if (files::exists(formatDir))
-            dirs.push_back(formatDir);
-    }
-    return dirs;
-}
-
-std::vector<std::string>
-makeLayoutDirs(std::vector<std::string> const& roots, std::string_view ext)
-{
-    std::vector<std::string> dirs;
-    dirs.reserve(roots.size());
-    for (auto const& root : roots)
-    {
-        auto const dir = files::appendPath(root, "generator", ext, "layouts");
-        if (files::exists(dir))
-            dirs.push_back(dir);
-    }
-    return dirs;
-}
+    Recursively scans the specified directory for `.hbs` files and
+    registers each as a Handlebars partial. The partial name is derived
+    from the file's relative path (without extension), allowing
+    subdirectory organization (e.g., `components/button.hbs` becomes
+    partial `components/button`).
 
+    @param hbs The Handlebars instance to register partials with.
+    @param partialsPath The directory path to scan for partial files.
+*/
 void
 loadPartials(
     Handlebars& hbs,
@@ -126,19 +80,22 @@ loadPartials(
     }
 }
 
-/* Make a URL relative to another URL.
+/** Makes a URL relative to another URL.
 
-   This function is a version of the Antora `relativize` helper,
-   used to create relative URLs between two paths in Antora projects.
+    This function implements Antora-style URL relativization, creating
+    relative URLs between two paths. It takes a target path (`to`) and
+    a source path (`from`), returning a relative path from `from` to `to`.
 
-   The function takes two paths, `to` and `from`, and returns a
-   relative path from `from` to `to`.
+    When called with a single argument, the current symbol's URL (from
+    `data.root.symbol.url`) is used as the source path.
 
-   If `from` is not provided, then the URL of the symbol being
-   rendered is used as the `from` path.
+    @param to0 The target URL to make relative.
+    @param from0 The source URL to relativize from (optional).
+    @param options Handlebars options containing context data.
+    @return The relative URL path, or the original URL if not absolute.
 
-   @see https://gitlab.com/antora/antora-ui-default/-/blob/master/src/helpers/relativize.js
- */
+    @see https://gitlab.com/antora/antora-ui-default/-/blob/master/src/helpers/relativize.js
+*/
 dom::Value
 relativize_fn(dom::Value to0, dom::Value from0, dom::Value options)
 {
@@ -214,15 +171,35 @@ relativize_fn(dom::Value to0, dom::Value from0, dom::Value options)
     return relativePath;
 }
 
-// Registration helpers
+/** Registers partial templates from multiple directories.
 
+    Iterates through each directory and loads all `.hbs` files as
+    Handlebars partials. Later directories in the list can override
+    partials from earlier ones, enabling supplemental addons to
+    customize templates.
+
+    @param hbs The Handlebars instance to register partials with.
+    @param dirs The list of directories to load partials from.
+*/
 void
 registerPartials(Handlebars& hbs, std::vector<std::string> const& dirs)
 {
     for (auto const& dir : dirs)
         loadPartials(hbs, dir);
 }
 
+/** Registers default Handlebars Generator helpers.
+
+    Registers the default set of helpers available in all templates:
+    - `primary_location`: Returns the primary source location for a symbol
+    - `relativize`: Creates relative URLs between paths
+    - Constructor, string, Antora, logical, math, container, and type helpers
+
+    These helpers are registered before user-defined helpers, allowing
+    users to override built-in behavior if needed.
+
+    @param hbs The Handlebars instance to register helpers with.
+*/
 void
 registerDefaultHelpers(Handlebars& hbs)
 {
@@ -263,6 +240,24 @@ registerDefaultHelpers(Handlebars& hbs)
     hbs.registerHelper("relativize", dom::makeInvocable(relativize_fn));
 }
 
+/** Registers user-defined JavaScript helpers from addon directories.
+
+    Scans the specified directories for JavaScript files and registers
+    them as Handlebars helpers. Files are categorized into two types:
+
+    - **Utility files** (prefixed with `_`): Executed as scripts to define
+      shared globals. Loaded alphabetically before helper files.
+    - **Helper files**: Registered as Handlebars helpers with the filename
+      (minus `.js`) as the helper name.
+
+    This separation allows helpers to share common code through utilities
+    without duplicating implementations.
+
+    @param hbs The Handlebars instance to register helpers with.
+    @param ctx The JavaScript context for script execution.
+    @param helperDirs The directories to scan for helper files.
+    @return Success, or an error if loading/registration fails.
+*/
 Expected<void>
 registerUserHelpers(
     Handlebars& hbs,
@@ -340,6 +335,17 @@ registerUserHelpers(
     return {};
 }
 
+/** Loads a layout template from addon directories.
+
+    Searches through the layout directories for the specified template
+    file. If found in multiple directories, later directories override
+    earlier ones (enabling supplemental addons to customize layouts).
+
+    @param templates The map to store loaded templates (filename -> content).
+    @param layoutDirs The directories to search for the template.
+    @param filename The template filename to load (e.g., "index.html.hbs").
+    @return Success, or throws an error if the template is not found.
+ */
 Expected<void, Error>
 loadLayoutTemplate(
     std::map<std::string, std::string, std::less<>>& templates,
@@ -374,9 +380,9 @@ Builder(
 
     auto const& config = domCorpus->config;
     auto const roots = addon_paths::addonRoots(config);
-    auto const partialDirs = makePartialDirs(roots, domCorpus.fileExtension);
-    auto const helperDirs = makeHelperDirs(roots, domCorpus.fileExtension);
-    auto const layoutDirs = makeLayoutDirs(roots, domCorpus.fileExtension);
+    auto const partialDirs = addon_paths::partialDirs(roots, domCorpus.fileExtension);
+    auto const helperDirs = addon_paths::helperDirs(roots, domCorpus.fileExtension);
+    auto const layoutDirs = addon_paths::layoutDirs(roots, domCorpus.fileExtension);
 
     // Load partials (later dirs overwrite earlier ones because we walk in order)
     registerPartials(hbs_, partialDirs);