feat: support script-driven generators

This adds a generator flavor backed by a user script. A directory under
<addon>/generator/<name>/ whose mrdocs-generator.yml names a script
entry installs a generator that hands the whole emit to a Lua or
JavaScript `generate(corpus, output)` function: the script walks the
corpus and writes files through the output object, so it can produce
output shapes a per-page generator cannot, such as a single artifact
aggregated across every symbol.

The manifest parser moves into a shared `GeneratorManifest`, so the
data-driven and script-driven discovery passes read the same file. A
manifest that names a script is skipped by the data-driven pass and
installed by the script pass.

The output object exposes a single write method, resolved under the
output directory and forbidden from escaping it. Both languages receive
it as the second argument to generate; on the Lua side it is also bound
as a global and passed from there, because the Lua bridge cannot carry a
callable as a plain value.

Author: gennaroprota

src/lib/Gen/GeneratorManifest.cpp

@@ -0,0 +1,195 @@
+//
+// 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) 2026 Gennaro Prota (gennaro.prota@gmail.com)
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#include "GeneratorManifest.hpp"
+#include <mrdocs/Support/Path.hpp>
+#include <llvm/ADT/SmallString.h>
+#include <llvm/Support/Casting.h>
+#include <llvm/Support/SourceMgr.h>
+#include <llvm/Support/YAMLParser.h>
+#include <filesystem>
+
+namespace mrdocs {
+
+namespace {
+
+// Read a scalar node into an owned string.
+std::string
+scalarText(llvm::yaml::ScalarNode& node)
+{
+    llvm::SmallString<32> buf;
+    llvm::StringRef const text = node.getValue(buf);
+    return std::string(text.data(), text.size());
+}
+
+// Parse a YAML mapping whose entries are non-empty byte-sequence keys
+// mapped to replacement strings. An empty key is a hard error.
+Expected<void>
+parseEscape(
+    llvm::yaml::MappingNode& node,
+    GeneratorManifest& manifest,
+    std::string_view yamlPath)
+{
+    for (llvm::yaml::KeyValueNode& entry : node)
+    {
+        llvm::yaml::ScalarNode* const keyNode =
+            llvm::dyn_cast_or_null<llvm::yaml::ScalarNode>(entry.getKey());
+        llvm::yaml::ScalarNode* const valNode =
+            llvm::dyn_cast_or_null<llvm::yaml::ScalarNode>(entry.getValue());
+        if (!keyNode || !valNode)
+        {
+            return Unexpected(formatError(
+                "{}: each 'escape' entry must be a scalar->scalar mapping",
+                yamlPath));
+        }
+        std::string key = scalarText(*keyNode);
+        if (key.empty())
+        {
+            return Unexpected(formatError(
+                "{}: escape key must not be empty", yamlPath));
+        }
+        manifest.escape.emplace_back(
+            std::move(key), scalarText(*valNode));
+    }
+    return {};
+}
+
+// Dispatch a single top-level manifest key to its handler. Unknown keys
+// are ignored so future schema additions stay non-breaking.
+Expected<void>
+parseTopLevelEntry(
+    llvm::yaml::KeyValueNode& pair,
+    GeneratorManifest& manifest,
+    std::string_view yamlPath)
+{
+    llvm::yaml::ScalarNode* const keyNode =
+        llvm::dyn_cast_or_null<llvm::yaml::ScalarNode>(pair.getKey());
+    if (!keyNode)
+    {
+        return {};
+    }
+    llvm::SmallString<16> keyBuf;
+    llvm::StringRef const key = keyNode->getValue(keyBuf);
+    if (key == "escape")
+    {
+        llvm::yaml::MappingNode* const escNode =
+            llvm::dyn_cast_or_null<llvm::yaml::MappingNode>(pair.getValue());
+        if (!escNode)
+        {
+            return Unexpected(formatError(
+                "{}: 'escape' must be a mapping", yamlPath));
+        }
+        return parseEscape(*escNode, manifest, yamlPath);
+    }
+    if (key == "script")
+    {
+        llvm::yaml::ScalarNode* const valNode =
+            llvm::dyn_cast_or_null<llvm::yaml::ScalarNode>(pair.getValue());
+        if (!valNode)
+        {
+            return Unexpected(formatError(
+                "{}: 'script' must be a scalar", yamlPath));
+        }
+        manifest.script = scalarText(*valNode);
+    }
+    return {};
+}
+
+} // (anon)
+
+Expected<GeneratorManifest>
+loadGeneratorManifest(std::string_view yamlPath)
+{
+    MRDOCS_TRY(std::string text, files::getFileText(yamlPath));
+    llvm::SourceMgr sm;
+    llvm::yaml::Stream stream(text, sm);
+
+    GeneratorManifest manifest;
+    llvm::yaml::document_iterator docIt = stream.begin();
+    if (docIt == stream.end())
+    {
+        return manifest;
+    }
+    llvm::yaml::Node* const rootNode = docIt->getRoot();
+    if (rootNode == nullptr ||
+        llvm::isa<llvm::yaml::NullNode>(rootNode))
+    {
+        // Empty document: a file with no content, only comments, or a
+        // literal `null`. All of these mean "no rules".
+        return manifest;
+    }
+    llvm::yaml::MappingNode* const root =
+        llvm::dyn_cast<llvm::yaml::MappingNode>(rootNode);
+    if (!root)
+    {
+        return Unexpected(formatError(
+            "{}: top-level YAML node must be a mapping", yamlPath));
+    }
+    for (llvm::yaml::KeyValueNode& pair : *root)
+    {
+        MRDOCS_TRY(parseTopLevelEntry(pair, manifest, yamlPath));
+    }
+    return manifest;
+}
+
+namespace {
+
+constexpr std::string_view metadataFileName = "mrdocs-generator.yml";
+
+// Append every manifested subdirectory of `generatorDir` to `out`.
+Expected<void>
+scanGeneratorDir(
+    std::string_view generatorDir,
+    std::vector<DiscoveredManifest>& out)
+{
+    namespace fs = std::filesystem;
+    std::error_code iterEc;
+    fs::directory_iterator const end{};
+    for (fs::directory_iterator it(generatorDir, iterEc);
+         !iterEc && it != end;
+         it.increment(iterEc))
+    {
+        std::error_code typeEc;
+        if (!it->is_directory(typeEc))
+        {
+            continue;
+        }
+        std::string const dir = it->path().string();
+        std::string const yamlPath = files::appendPath(
+            dir, std::string(metadataFileName));
+        if (!files::exists(yamlPath))
+        {
+            continue;
+        }
+        MRDOCS_TRY(GeneratorManifest manifest, loadGeneratorManifest(yamlPath));
+        out.push_back(DiscoveredManifest{ dir, std::move(manifest) });
+    }
+    return {};
+}
+
+} // (anon)
+
+Expected<std::vector<DiscoveredManifest>>
+discoverGeneratorManifests(std::vector<std::string> const& roots)
+{
+    std::vector<DiscoveredManifest> out;
+    for (std::string const& root : roots)
+    {
+        std::string const dir = files::appendPath(root, "generator");
+        if (!files::exists(dir))
+        {
+            continue;
+        }
+        MRDOCS_TRY(scanGeneratorDir(dir, out));
+    }
+    return out;
+}
+
+} // mrdocs

src/lib/Gen/GeneratorManifest.hpp

@@ -0,0 +1,104 @@
+//
+// 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) 2026 Gennaro Prota (gennaro.prota@gmail.com)
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_LIB_GEN_GENERATORMANIFEST_HPP
+#define MRDOCS_LIB_GEN_GENERATORMANIFEST_HPP
+
+#include <mrdocs/Support/Error.hpp>
+#include <mrdocs/Support/Expected.hpp>
+#include <optional>
+#include <string>
+#include <string_view>
+#include <utility>
+#include <vector>
+
+namespace mrdocs {
+
+/** The parsed contents of a generator manifest.
+
+    A manifest is the `mrdocs-generator.yml` that an addon directory
+    under <root>/generator/<name>/ ships to declare a generator. The two
+    generator flavors read disjoint fields of the same file:
+
+    @li A data-driven (Handlebars) generator reads the escape rules.
+
+    @li A script-driven generator reads the entry-file path.
+
+    The presence of the `script` entry is what distinguishes the two: a
+    manifest that names a `script` is a script-driven generator,
+    otherwise it is data-driven.
+*/
+struct GeneratorManifest
+{
+    /** The entry file of a script-driven generator.
+
+        Holds the value of the manifest's optional `script` key, a path
+        relative to the generator directory. Empty when the manifest
+        declares no `script`, in which case the directory is a
+        data-driven generator.
+    */
+    std::optional<std::string> script;
+
+    /** The escape rules of a data-driven generator.
+
+        Each pair maps a byte-sequence source to its replacement string,
+        in manifest order. Empty when no escape rules are declared.
+    */
+    std::vector<std::pair<std::string, std::string>> escape;
+};
+
+/** Parse a generator manifest into plain data.
+
+    Read the file at `yamlPath` and return its contents. The file is
+    expected to contain a top-level mapping. The optional `escape` key
+    holds a sub-mapping from byte-sequence keys to replacement strings;
+    keys may be one or more bytes long, and an empty key is a hard error.
+    The optional `script` key holds the entry-file path as a scalar.
+    Unknown top-level keys are ignored so future schema additions are
+    non-breaking.
+
+    An empty document (an empty file, comments only, or a literal `null`)
+    yields an empty manifest.
+*/
+Expected<GeneratorManifest>
+loadGeneratorManifest(std::string_view yamlPath);
+
+/** A generator directory paired with its parsed manifest.
+*/
+struct DiscoveredManifest
+{
+    /** The generator directory, of the form <root>/generator/<name>.
+    */
+    std::string dir;
+
+    /** The parsed contents of the directory's manifest.
+    */
+    GeneratorManifest manifest;
+};
+
+/** Find every addon generator directory that ships a manifest.
+
+    For each addon root, walk the immediate subdirectories of
+    <root>/generator/. A subdirectory is reported when it ships an
+    `mrdocs-generator.yml`; the manifest is parsed and returned alongside
+    its directory. Directories without a manifest (the built-in shared
+    common/ is the canonical example) are skipped.
+
+    The presence of a `script` entry distinguishes the two generator
+    flavors, so a caller installs the flavor it owns and ignores the
+    other. Roots are searched in order, so the result preserves addon
+    precedence.
+*/
+Expected<std::vector<DiscoveredManifest>>
+discoverGeneratorManifests(std::vector<std::string> const& roots);
+
+} // mrdocs
+
+#endif