refactor(extensions): register scripts through a mrdocs object, not globals

`register_transform` and `register_generator` were bare globals in the
extension environment. This moves them onto a `mrdocs` global object,
the way `console` is already provided, so a script writes
`mrdocs.register_transform(fn)` / `mrdocs.register_generator(id, fn)`.

Among Lua-embedding applications that expose a "register an extension"
call, a host namespace object is the prevailing convention - darktable
uses `dt.register_*`, Aegisub `aegisub.register_*`, Redis
`redis.register_function` - while bare globals are the exception. The
main advantage of exposing an object is that it makes the surface
discoverable.

Note that the per-invocation `ctx` (`ctx.corpus`, `ctx.output`,
`ctx.config`) is unchanged: only load-time declarations go through
`mrdocs`.

Author: gennaroprota

docs/modules/ROOT/pages/extensions/corpus-extensions.adoc

@@ -5,7 +5,7 @@ An extension is a Lua or JavaScript script that runs as part of a Mr.Docs build
 * A *corpus transform* rewrites metadata across many symbols at once: backfill briefs from a naming convention, tag symbols by group, mark generated code as "see below" in the output. Transforms run between extraction and rendering, so every generator sees the change.
 * A *generator* owns the whole emit: instead of rendering one page per symbol, it traverses the corpus and writes whatever files it wants. That lets it produce shapes the per-page generators cannot, such as a single artifact aggregated across every symbol.
 
-A script declares a transform with `register_transform(fn)` and a generator with `register_generator(id, fn)`. Either way the registered function receives a single context object, `ctx`.
+A script declares a transform with `mrdocs.register_transform(fn)` and a generator with `mrdocs.register_generator(id, fn)`. Either way the registered function receives a single context object, `ctx`.
 
 == Languages and addon locations
 
@@ -33,7 +33,7 @@ A script can register any number of transforms and generators, or none at all. I
 [#corpus-transforms]
 == Corpus transforms
 
-A transform is a function passed to `register_transform`. Mr.Docs invokes each registered function once, in registration order, with the `ctx` object. A flat view of the corpus reaches the script through `ctx.corpus`.
+A transform is a function passed to `mrdocs.register_transform`. Mr.Docs invokes each registered function once, in registration order, with the `ctx` object. A flat view of the corpus reaches the script through `ctx.corpus`.
 
 [tabs]
 ======
@@ -65,7 +65,7 @@ JavaScript::
 .`addons/extensions/count_by_kind.js`
 [source,javascript]
 ----
-register_transform(function(ctx) {
+mrdocs.register_transform(function(ctx) {
     var counts = {};
     for (var i = 0; i < ctx.corpus.symbols.length; ++i) {
         var k = ctx.corpus.symbols[i].kind;
@@ -82,7 +82,7 @@ Lua::
 .`addons/extensions/count_by_kind.lua`
 [source,lua]
 ----
-register_transform(function(ctx)
+mrdocs.register_transform(function(ctx)
     local counts = {}
     for _, sym in ipairs(ctx.corpus.symbols) do
         counts[sym.kind] = (counts[sym.kind] or 0) + 1
@@ -225,7 +225,7 @@ Notice in this example that `s.doc.sees` receives a list of polymorphic types th
 
 The built-in generators render one page per symbol. When you need a different output structure, e.g. one file per namespace, or a single artifact aggregated across every symbol such as a search index, that page-per-symbol shape cannot express it. A generator hands the whole emit to the script instead: it traverses the corpus and writes whatever files it wants. No C++ and no templates are involved.
 
-A script declares a generator with `register_generator(id, fn)`. The `id` is the name you select on the command line with `--generator=<id>`; a registered generator takes precedence over a built-in of the same name. Selecting a generator is a request for output, so its function does the work directly, the page-per-symbol fallback the built-ins provide does not apply.
+A script declares a generator with `mrdocs.register_generator(id, fn)`. The `id` is the name you select on the command line with `--generator=<id>`; a registered generator takes precedence over a built-in of the same name. Selecting a generator is a request for output, so its function does the work directly, the page-per-symbol fallback the built-ins provide does not apply.
 
 The function receives the same `ctx` a transform does, plus `ctx.output`:
 

docs/mrdocs.schema.json

@@ -282,7 +282,7 @@
       "default": [
         "html"
       ],
-      "description": "The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The built-in generators include `adoc`, `html`, `xml`, and `noop` (which extracts but writes no output, useful for checking extraction warnings); data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/; a script-driven generator is declared by an extension with `register_generator` and produces the output itself. This option accepts a single generator (`generator: xml`), a list (`generator: [xml, adoc]`), or a comma-separated string (`generator: \"xml,adoc\"`); when more than one is given the documentation is produced once per generator.",
+      "description": "The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The built-in generators include `adoc`, `html`, `xml`, and `noop` (which extracts but writes no output, useful for checking extraction warnings); data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/; a script-driven generator is declared by an extension with `mrdocs.register_generator` and produces the output itself. This option accepts a single generator (`generator: xml`), a list (`generator: [xml, adoc]`), or a comma-separated string (`generator: \"xml,adoc\"`); when more than one is given the documentation is produced once per generator.",
       "title": "Generator(s) used to create the documentation"
     },
     "global-namespace-index": {

examples/generators/script-driven/search-index/addons/extensions/search_index.lua

@@ -2,8 +2,8 @@
 -- aggregates every symbol into a single search-index.json, the kind of
 -- artifact the per-page generators cannot produce.
 --
--- `register_generator(id, fn)` declares it next to any
--- `register_transform` a script might also declare; selecting
+-- `mrdocs.register_generator(id, fn)` declares it next to any
+-- `mrdocs.register_transform` a script might also declare; selecting
 -- `generator: <id>` runs `fn` with one `ctx`. `ctx.corpus.symbols` is
 -- every symbol (each tagged with a flat `_id` so the generator can form
 -- stable per-symbol URLs) and `ctx.output.write` emits files under the
@@ -15,7 +15,7 @@ local function json_string(s)
   return '"' .. s .. '"'
 end
 
-register_generator("search-index", function(ctx)
+mrdocs.register_generator("search-index", function(ctx)
   local entries = {}
   for _, sym in ipairs(ctx.corpus.symbols) do
     local name = sym.name or ""

src/lib/ConfigOptions.json

@@ -443,7 +443,7 @@
       {
         "name": "generator",
         "brief": "Generator(s) used to create the documentation",
-        "details": "The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The built-in generators include `adoc`, `html`, `xml`, and `noop` (which extracts but writes no output, useful for checking extraction warnings); data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/; a script-driven generator is declared by an extension with `register_generator` and produces the output itself. This option accepts a single generator (`generator: xml`), a list (`generator: [xml, adoc]`), or a comma-separated string (`generator: \"xml,adoc\"`); when more than one is given the documentation is produced once per generator.",
+        "details": "The generator is responsible for creating the documentation from the extracted symbols. The generator uses the extracted symbols and the templates to create the documentation. The built-in generators include `adoc`, `html`, `xml`, and `noop` (which extracts but writes no output, useful for checking extraction warnings); data-driven generators can be added by dropping a template folder under <addon>/generator/<name>/; a script-driven generator is declared by an extension with `mrdocs.register_generator` and produces the output itself. This option accepts a single generator (`generator: xml`), a list (`generator: [xml, adoc]`), or a comma-separated string (`generator: \"xml,adoc\"`); when more than one is given the documentation is produced once per generator.",
         "type": "string-list",
         "default": ["html"]
       },

src/lib/CorpusImpl.hpp

@@ -62,7 +62,7 @@ class CorpusImpl final : public Corpus
     std::map<SymbolID, UnorderedStringMap<Symbol const*>> lookupCache_;
 
     // Output generators an extension script defined via
-    // `register_generator(id, fn)`. Each `fn` is a `dom::Function` that
+    // `mrdocs.register_generator(id, fn)`. Each `fn` is a `dom::Function` that
     // stays runnable until this corpus is destroyed (after extensions run,
     // when a generator is selected). Its scripting VM is kept alive either
     // by the function itself or by a matching entry in
@@ -217,8 +217,8 @@ class CorpusImpl final : public Corpus
 
     /** Register a script-defined output generator.
 
-        Called from an extension's `register_generator(id, fn)`. The first
-        registration of a given id wins; later ones are ignored.
+        Called from an extension's `mrdocs.register_generator(id, fn)`.
+        The first registration of a given id wins; later ones are ignored.
     */
     void
     registerScriptGenerator(std::string id, dom::Function fn);
@@ -230,7 +230,7 @@ class CorpusImpl final : public Corpus
 
     /** Keep a scripting VM alive for the lifetime of this corpus.
 
-        A generator registered via `register_generator` may hold only a
+        A generator registered via `mrdocs.register_generator` may hold only a
         weak reference to the VM that defined it. The extension binding
         hands the VM over here so it outlives the extension run and stays
         usable when the generator is selected.

src/lib/Extensions/JsBinding.cpp

@@ -27,19 +27,20 @@ namespace mrdocs {
 
 namespace {
 
-// Bind the `register_transform` and `register_generator` entry points
-// before the script runs. A JavaScript function bridges to a
-// `dom::Function`: transforms are captured in `transforms` (invoked once
-// the script has run), generators are handed to the corpus, which keeps
-// them runnable past this VM's lifetime.
+// Install the `mrdocs` global carrying the `register_transform` and
+// `register_generator` entry points before the script runs. A JavaScript
+// function bridges to a `dom::Function`: transforms are captured in
+// `transforms` (invoked once the script has run), generators are handed to
+// the corpus, which keeps them runnable past this VM's lifetime.
 void
 registerJsExtensionApi(
     js::Scope& scope,
     CorpusImpl& corpus,
     dom::Array& transforms,
     std::size_t& generators)
 {
-    scope.setGlobal(
+    dom::Object api;
+    api.set(
         "register_transform",
         dom::Value(dom::makeVariadicInvocable(
             [&transforms](dom::Array const& args)
@@ -49,7 +50,8 @@ registerJsExtensionApi(
                 if (args.empty() || !args.get(0).isFunction())
                 {
                     result = Unexpected(Error(
-                        "register_transform: expected a function argument"));
+                        "mrdocs.register_transform: expected a function "
+                        "argument"));
                 }
                 else
                 {
@@ -58,7 +60,7 @@ registerJsExtensionApi(
                 return result;
             })));
 
-    scope.setGlobal(
+    api.set(
         "register_generator",
         dom::Value(dom::makeVariadicInvocable(
             [&corpus, &generators](dom::Array const& args)
@@ -70,7 +72,8 @@ registerJsExtensionApi(
                     !args.get(1).isFunction())
                 {
                     result = Unexpected(Error(
-                        "register_generator: expected (string id, function)"));
+                        "mrdocs.register_generator: expected (string id, "
+                        "function)"));
                 }
                 else
                 {
@@ -81,6 +84,8 @@ registerJsExtensionApi(
                 }
                 return result;
             })));
+
+    scope.setGlobal("mrdocs", dom::Value(std::move(api)));
 }
 
 // Invoke one registered transform with the `ctx` object, tagging any
@@ -127,7 +132,7 @@ runOneJsExtension(CorpusImpl& corpus, std::string const& scriptPath)
 
     MRDOCS_TRY(std::string script, files::getFileText(scriptPath));
 
-    // Running the script is what calls `register_transform`.
+    // Running the script is what calls `mrdocs.register_transform`.
     Expected<void> result = scope.script(script);
     if (!result.has_value())
     {
@@ -138,7 +143,8 @@ runOneJsExtension(CorpusImpl& corpus, std::string const& scriptPath)
     else if (transforms.empty() && generators == 0)
     {
         // A discovered script that registers nothing is almost always a
-        // mistake (a misspelled `register_transform` / `register_generator`,
+        // mistake (a misspelled `mrdocs.register_transform` /
+        // `mrdocs.register_generator`,
         // or a guard that skipped it), so flag it rather than silently
         // doing nothing.
         report::warn("extension '{}' registered nothing", scriptPath);

src/lib/Extensions/JsBinding.hpp

@@ -22,10 +22,11 @@ class CorpusImpl;
 /** Run one JavaScript extension script against the corpus.
 
     Build a fresh JS context and evaluate the script. The script declares
-    corpus transforms with `register_transform(fn)` and output generators
-    with `register_generator(id, fn)`, in either combination. Each transform
-    is invoked once, in registration order, with a navigable DOM view of the
-    corpus it can read and mutate in place; each generator is handed to the
+    corpus transforms with `mrdocs.register_transform(fn)` and output
+    generators with `mrdocs.register_generator(id, fn)`, in either
+    combination. Each transform is invoked once, in registration order,
+    with a navigable DOM view of the corpus it can read and mutate in
+    place; each generator is handed to the
     corpus to run later, once one is selected. A script that registers
     nothing causes a warning and otherwise has no effect, so an empty .js
     file is tolerated.

src/lib/Extensions/LuaBinding.cpp

@@ -48,7 +48,7 @@ struct LuaRegistrations
     std::size_t generators = 0;
 };
 
-// `register_transform(fn)`: anchor `fn` in the registry and record it as
+// `mrdocs.register_transform(fn)`: anchor `fn` in the registry and record it as
 // a callable, so the host can invoke it once the chunk has run.
 int
 luaRegisterTransform(lua_State* L)
@@ -59,7 +59,7 @@ luaRegisterTransform(lua_State* L)
     if (lua_type(L, 1) != LUA_TFUNCTION)
     {
         result = luaL_error(L,
-            "register_transform: expected a function argument");
+            "mrdocs.register_transform: expected a function argument");
     }
     else
     {
@@ -70,9 +70,10 @@ luaRegisterTransform(lua_State* L)
     return result;
 }
 
-// `register_generator(id, fn)`: anchor `fn` in the registry and hand it to
-// the corpus under `id`. The corpus keeps it runnable until a generator is
-// selected and run, long after this chunk's stack has unwound.
+// `mrdocs.register_generator(id, fn)`: anchor `fn` in the registry and
+// hand it to the corpus under `id`. The corpus keeps it runnable until a
+// generator is selected and run, long after this chunk's stack has
+// unwound.
 int
 luaRegisterGenerator(lua_State* L)
 {
@@ -82,7 +83,7 @@ luaRegisterGenerator(lua_State* L)
     if (lua_type(L, 1) != LUA_TSTRING || lua_type(L, 2) != LUA_TFUNCTION)
     {
         result = luaL_error(L,
-            "register_generator: expected (string id, function)");
+            "mrdocs.register_generator: expected (string id, function)");
     }
     else
     {
@@ -98,22 +99,24 @@ luaRegisterGenerator(lua_State* L)
     return result;
 }
 
-// Bind the `register_transform` and `register_generator` entry points
-// before the chunk runs. The shared registrations pointer is carried as
-// each closure's single upvalue.
+// Install the `mrdocs` global carrying the `register_transform` and
+// `register_generator` entry points before the chunk runs. The shared
+// registrations pointer is carried as each closure's single upvalue.
 void
 registerLuaExtensionApi(
     lua::Context& ctx, CorpusImpl& corpus, LuaRegistrations& regs)
 {
     regs.ctx = &ctx;
     regs.corpus = &corpus;
     lua_State* L = static_cast<lua_State*>(ctx.nativeState());
+    lua_newtable(L);
     lua_pushlightuserdata(L, &regs);
     lua_pushcclosure(L, &luaRegisterTransform, 1);
-    lua_setglobal(L, "register_transform");
+    lua_setfield(L, -2, "register_transform");
     lua_pushlightuserdata(L, &regs);
     lua_pushcclosure(L, &luaRegisterGenerator, 1);
-    lua_setglobal(L, "register_generator");
+    lua_setfield(L, -2, "register_generator");
+    lua_setglobal(L, "mrdocs");
 }
 
 // Invoke one registered transform with the `ctx` object, tagging any
@@ -158,11 +161,12 @@ runOneLuaExtension(CorpusImpl& corpus, std::string const& scriptPath)
     MRDOCS_TRY(lua::Function chunk, scope.loadChunk(script, scriptPath));
 
     // Running the chunk's top-level code is what calls
-    // `register_transform`; the chunk's own return value is unused.
+    // `mrdocs.register_transform`; the chunk's own return value is unused.
     MRDOCS_TRY(chunk.call());
 
     // A discovered script that registers nothing is almost always a
-    // mistake (a misspelled `register_transform` / `register_generator`,
+    // mistake (a misspelled `mrdocs.register_transform` /
+    // `mrdocs.register_generator`,
     // or a guard that skipped it), so flag it rather than silently doing
     // nothing.
     if (regs.transforms.empty() && regs.generators == 0)

src/lib/Extensions/LuaBinding.hpp

@@ -22,10 +22,11 @@ class CorpusImpl;
 /** Run one Lua extension script against the corpus.
 
     Build a fresh Lua context and evaluate the script. The script declares
-    corpus transforms with `register_transform(fn)` and output generators
-    with `register_generator(id, fn)`, in either combination. Each transform
-    is invoked once, in registration order, with a navigable DOM view of the
-    corpus it can read and mutate in place; each generator is handed to the
+    corpus transforms with `mrdocs.register_transform(fn)` and output
+    generators with `mrdocs.register_generator(id, fn)`, in either
+    combination. Each transform is invoked once, in registration order,
+    with a navigable DOM view of the corpus it can read and mutate in
+    place; each generator is handed to the
     corpus to run later, once one is selected. A script that registers
     nothing causes a warning and otherwise has no effect, so an empty .lua
     file is tolerated.

src/lib/Extensions/RunExtensions.hpp

@@ -23,7 +23,7 @@ class CorpusImpl;
     Extensions are discovered under each addon root's extensions/
     directory (the primary addons plus addons-supplemental): a .lua or
     .js file is an extension. Each script declares corpus transforms by
-    calling `register_transform(fn)`; every registered function is
+    calling `mrdocs.register_transform(fn)`; every registered function is
     invoked once, in registration order, with a navigable DOM view of the
     corpus. A transform reads the corpus through that view and mutates it
     by assigning to symbol fields (for example `sym.name = "..."`), which