Hoist templateGlobalVars merge, update JSDoc to reflect new contract

Merges globalVars and globalDataVars once before the pMap loop instead
of once per template render. Updates TemplateFunction and templateBuilder
JSDoc to accurately describe that vars now includes global.data.js output.

Author: bcomnes

lib/build-pages/index.js

@@ -254,6 +254,9 @@ export async function buildPagesDirect (src, dest, siteData, _opts) {
     ? siteData.templates.filter(t => templateFilterSet.has(t.templateFile.filepath))
     : siteData.templates
 
+  // Merge once — globalVars and globalDataVars are constant for this build.
+  const templateGlobalVars = { ...globalVars, ...globalDataVars }
+
   await Promise.all([
     pMap(pagesToRender, async (page) => {
       try {
@@ -276,7 +279,7 @@ export async function buildPagesDirect (src, dest, siteData, _opts) {
         const buildResult = await templateBuilder({
           src,
           dest,
-          globalVars: { ...globalVars, ...globalDataVars },
+          globalVars: templateGlobalVars,
           template,
           pages,
         })

lib/build-pages/page-builders/template-builder.js

@@ -17,7 +17,7 @@ import { writeFile, mkdir } from 'fs/promises'
  * @template {Record<string, any>} T - The type of variables for the template
  * @callback TemplateFunction
  * @param {object} params - The parameters for the template.
- * @param {T} params.vars - All of the site globalVars.
+ * @param {T} params.vars - All of the site globalVars merged with global.data.js output.
  * @param {TemplateInfo} params.template - Info about the current template
  * @param {PageData<T, any, string>[]} params.pages - An array of info about every page
  * @returns {Promise<string | TemplateOutputOverride | TemplateOutputOverride[]>}
@@ -46,12 +46,13 @@ import { writeFile, mkdir } from 'fs/promises'
  */
 
 /**
- * The template builder renders templates agains the globalVars variables
+ * The template builder renders templates against the globalVars variables.
+ * globalVars passed here already includes global.data.js output merged in.
  * @template {Record<string, any>} T - The type of global variables for the template builder
  * @param {object}  params
  * @param  {string} params.src        - The src path of the site build.
  * @param  {string} params.dest       - The dest path of the site build.
- * @param  {T} params.globalVars - The resolvedGlobal vars object.
+ * @param  {T} params.globalVars - globalVars merged with global.data.js output.
  * @param  {TemplateInfo} params.template   - The TemplateInfo of the template.
  * @param  {PageData<T, any, string>[]} params.pages      - The array of PageData object.
  */