refactor(test): defer generator lookup until the per-test settings load

Generator lookup happened once at `TestRunner` construction. With
data-driven Handlebars generators now possible, a generator
contributed via a test's `addons-supplemental` was unreachable from the
test binary: the lookup ran before that test's mrdocs.yml had been
loaded, so the generator wasn't yet registered.

The runner now defers the lookup. The built-in generators are not
affected.

Author: gennaroprota

src/lib/Gen/hbs/AddonPaths.hpp

@@ -4,6 +4,7 @@
 // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
 //
 // Copyright (c) 2025 Alan de Freitas (alandefreitas@gmail.com)
+// Copyright (c) 2026 Gennaro Prota (gennaro.prota@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -21,6 +22,36 @@
 
 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 settings.
+
+    @param settings The configuration settings containing addon paths.
+    @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::Settings const& settings)
+{
+    std::vector<std::string> roots;
+    roots.reserve(1 + settings.addonsSupplemental.size());
+
+    if (files::exists(settings.addons))
+        roots.push_back(settings.addons);
+
+    for (auto const& supplemental : settings.addonsSupplemental)
+    {
+        if (files::exists(supplemental))
+            roots.push_back(supplemental);
+    }
+    return roots;
+}
+
+
 /** Returns directories containing Handlebars partial templates.
 
     For each addon root, this function looks for partial templates in:
@@ -133,7 +164,7 @@ findFile(
     std::string_view subdir,
     std::string_view filename)
 {
-    auto roots = mrdocs::addonRoots(config);
+    auto roots = addonRoots(config.settings());
     for (auto it = roots.rbegin(); it != roots.rend(); ++it)
     {
         std::string candidate = files::appendPath(*it, "generator", generator, subdir, filename);

src/lib/Gen/hbs/Builder.cpp

@@ -454,7 +454,7 @@ Builder(
     namespace fs = std::filesystem;
 
     auto const& config = domCorpus->config;
-    auto const roots = addonRoots(config);
+    auto const roots = addon_paths::addonRoots(config.settings());
     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);

src/test/Support/TestLayout.cpp

@@ -28,26 +28,46 @@ pathWithExtension(
 
 } // (anon)
 
-/** Build the per-file layout and normalized settings with mode validation. */
-Expected<ResolvedLayout>
-resolveTestLayout(
+/** Read any per-file mrdocs.yml on top of the directory-level settings. */
+Expected<LoadedTestSettings>
+loadTestSettings(
     llvm::StringRef filePath,
     Config::Settings const& dirSettings,
-    llvm::StringRef generatorExtension,
-    ReferenceDirectories const& dirs,
-    Action action)
+    ReferenceDirectories const& dirs)
 {
-    Config::Settings fileSettings = dirSettings;
-    auto configPath = files::withExtension(filePath, "yml");
-    bool const hasFileConfig = files::exists(configPath);
-    if (hasFileConfig)
+    LoadedTestSettings result;
+    result.settings = dirSettings;
+    result.dirMultipage = dirSettings.multipage;
+    std::string const configPath = files::withExtension(filePath, "yml");
+    result.hasFileConfig = files::exists(configPath);
+    if (result.hasFileConfig)
     {
-        if (auto exp = Config::Settings::load_file(fileSettings, configPath, dirs); !exp)
+        Expected<void> const exp = Config::Settings::load_file(
+            result.settings, configPath, dirs);
+        if (!exp)
         {
             return Unexpected(exp.error());
         }
     }
+    return result;
+}
 
+/** Build the layout, prepare multipage outputs, and normalize settings.
+    The split from loadTestSettings lets the caller run addon-generator
+    discovery in between, so the chosen generator's file extension is
+    known when paths are computed.
+*/
+Expected<ResolvedLayout>
+buildTestLayout(
+    llvm::StringRef filePath,
+    LoadedTestSettings loaded,
+    llvm::StringRef generatorExtension,
+    ReferenceDirectories const& dirs,
+    Action action)
+{
+    bool const dirMultipage = loaded.dirMultipage;
+    Config::Settings fileSettings = std::move(loaded.settings);
+    bool const hasFileConfig = loaded.hasFileConfig;
     bool const hasTagfileOverride = !fileSettings.tagfile.empty();
 
     TestLayout layout;
@@ -118,7 +138,7 @@ resolveTestLayout(
             return Unexpected(Error("multipage tests require a per-file mrdocs.yml with multipage: true"));
         }
 
-        if (dirSettings.multipage)
+        if (dirMultipage)
         {
             return Unexpected(Error("multipage defaults must remain disabled at the directory level"));
         }

src/test/Support/TestLayout.hpp

@@ -43,11 +43,42 @@ struct ResolvedLayout
     TestLayout layout;
 };
 
-/** Resolve per-test settings + layout, enforcing single vs multipage rules. */
-Expected<ResolvedLayout>
-resolveTestLayout(
+/** Settings produced by loadTestSettings before the layout is built.
+*/
+struct LoadedTestSettings
+{
+    Config::Settings settings;
+    /// True if a per-file mrdocs.yml was found and merged.
+    bool hasFileConfig = false;
+    /// Snapshot of the directory-level multipage flag before merging.
+    /// Used to enforce that multipage may only be enabled at the
+    /// per-file level.
+    bool dirMultipage = false;
+};
+
+/** Load any per-file mrdocs.yml on top of the directory-level settings.
+
+    No layout work is done here: the per-file settings are needed before
+    the test's generator is known, so addon discovery can run against
+    the merged addons paths.
+*/
+Expected<LoadedTestSettings>
+loadTestSettings(
     llvm::StringRef filePath,
     Config::Settings const& dirSettings,
+    ReferenceDirectories const& dirs);
+
+/** Build the per-file layout from already-loaded settings.
+
+    Computes expected-output paths, applies multipage handling (creating
+    the temporary output directory and adjusting the settings' output and
+    tagfile fields), normalizes the settings, and validates the
+    single vs multipage invariants.
+*/
+Expected<ResolvedLayout>
+buildTestLayout(
+    llvm::StringRef filePath,
+    LoadedTestSettings loaded,
     llvm::StringRef generatorExtension,
     ReferenceDirectories const& dirs,
     Action action);

src/test/TestRunner.cpp

@@ -5,6 +5,7 @@
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
 // Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
+// Copyright (c) 2026 Gennaro Prota (gennaro.prota@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -17,6 +18,7 @@
 #include "Support/Comparison.hpp"
 #include <lib/ConfigImpl.hpp>
 #include <lib/CorpusImpl.hpp>
+#include <lib/Gen/hbs/DataDrivenGenerators.hpp>
 #include <lib/MrDocsCompilationDatabase.hpp>
 #include <lib/SingleFileDB.hpp>
 #include <lib/Support/ExecuteAndWaitWithLogging.hpp>
@@ -37,9 +39,10 @@ namespace mrdocs {
 
 TestRunner::
 TestRunner(std::string_view generator)
-    : gen_(findGenerator(generator))
+    : genId_(generator)
 {
-    MRDOCS_ASSERT(gen_ != nullptr);
+    // The generator is looked up per-test in `handleFile`; after that,
+    // test's mrdocs.yml has been loaded and addon discovery has run.
 }
 
 namespace {
@@ -165,8 +168,37 @@ handleFile(
     if (!ensureRegularCpp(filePath))
         return;
 
-    auto resolved = resolveTestLayout(
-        filePath, dirSettings, gen_->fileExtension(), dirs_, testArgs.action);
+    // Load the per-file mrdocs.yml first so data-driven generators
+    // contributed via addons-supplemental are visible to discovery
+    // before the chosen generator is looked up.
+    //
+    // The generator registry is process-global and persists across
+    // tests. `discoverDataDrivenGenerators` is idempotent (it skips ids
+    // already installed), so re-running it per fixture is safe; but
+    // it also means the first fixture that registers a given id
+    // wins, and a later fixture that ships a generator directory
+    // with the same id will see its own contents quietly ignored.
+    Expected<LoadedTestSettings> loaded =
+        loadTestSettings(filePath, dirSettings, dirs_);
+    if (!loaded)
+    {
+        return report::error("{}: \"{}\"", loaded.error(), filePath);
+    }
+    Expected<void> discovered =
+        hbs::discoverDataDrivenGenerators(loaded->settings);
+    if (!discovered)
+    {
+        return report::error("{}: \"{}\"", discovered.error(), filePath);
+    }
+    Generator const* gen = findGenerator(genId_);
+    if (!gen)
+    {
+        return report::error(
+            "{}: the Generator \"{}\" was not found", filePath, genId_);
+    }
+
+    Expected<ResolvedLayout> resolved = buildTestLayout(
+        filePath, *std::move(loaded), gen->fileExtension(), dirs_, testArgs.action);
     if (!resolved)
     {
         return report::error("{}: \"{}\"", resolved.error(), filePath);
@@ -194,7 +226,7 @@ handleFile(
             db,
             config,
             defaultIncludePaths);
-        handleCompilationDatabase(filePath, compilations, config, layout);
+        handleCompilationDatabase(filePath, *gen, compilations, config, layout);
     };
 
     runWith({ "clang", "-std=c++23" });
@@ -204,6 +236,7 @@ handleFile(
 void
 TestRunner::handleCompilationDatabase(
     llvm::StringRef filePath,
+    Generator const& gen,
     MrDocsCompilationDatabase const& compilations,
     std::shared_ptr<ConfigImpl const> const& config,
     TestLayout const& layout)
@@ -219,7 +252,7 @@ TestRunner::handleCompilationDatabase(
     {
         test_support::SinglePageArgs args{
             layout,
-            *gen_,
+            gen,
             **corpus,
             filePath,
             testArgs.action,
@@ -237,7 +270,7 @@ TestRunner::handleCompilationDatabase(
     {
         test_support::MultipageArgs args{
             layout,
-            *gen_,
+            gen,
             **corpus,
             testArgs.action,
             testArgs.forceOption.getValue(),

src/test/TestRunner.hpp

@@ -5,6 +5,7 @@
 //
 // Copyright (c) 2023 Vinnie Falco (vinnie.falco@gmail.com)
 // Copyright (c) 2023 Alan de Freitas (alandefreitas@gmail.com)
+// Copyright (c) 2026 Gennaro Prota (gennaro.prota@gmail.com)
 //
 // Official repository: https://github.com/cppalliance/mrdocs
 //
@@ -55,7 +56,10 @@ struct TestResults
 class TestRunner
 {
     ThreadPool threadPool_;
-    Generator const* gen_;
+    /// Id of the chosen generator. Resolved per-test (after each test's
+    /// settings load) so that data-driven generators contributed via
+    /// addons-supplemental are picked up correctly.
+    std::string genId_;
     ReferenceDirectories dirs_;
 
     /** Run a single .cpp test file with inherited directory settings. */
@@ -80,6 +84,7 @@ class TestRunner
     void
     handleCompilationDatabase(
         llvm::StringRef filePath,
+        Generator const& gen,
         MrDocsCompilationDatabase const& compilations,
         std::shared_ptr<ConfigImpl const> const& config,
         TestLayout const& layout);

src/tool/GenerateAction.cpp

@@ -56,7 +56,7 @@ DoGenerateAction(
     // Handlebars layouts is registered as an additional generator
     // (subject to id and layout-template checks) before the user-
     // requested generator is looked up below.
-    MRDOCS_TRY(hbs::discoverDataDrivenGenerators(*config));
+    MRDOCS_TRY(hbs::discoverDataDrivenGenerators(config->settings()));
 
     // --------------------------------------------------------------
     //