Address PR #215 review comments

- Export globalVarsNames, globalDataNames, esbuildSettingsNames,
  markdownItSettingsNames, templateSuffixes from identify-pages.js and
  import them in index.js — eliminates duplicated (and nodeHasTS-unaware)
  constant definitions in the watch handler
- Add MAX_CONCURRENCY to index.js (consistent with build-pages/index.js)
  and use it in all three buildWatchMaps pMap calls instead of hardcoded 8
- findDepsOf now console.warn on failure instead of silently returning []
- Fix resolveVars JSDoc return type: always returns Promise<object>, not
  Promise<object|function>; remove stale type cast in buildWatchMaps
- Merge BuildPagesOpts into DomStackOpts (pageFilterPaths,
  templateFilterPaths); drop the separate 5th buildPagesOpts parameter
  from buildPages/buildPagesDirect — worker.js now destructures opts
- WorkerBuildStepResult is now a standalone typedef instead of
  Omit<PageBuildStepResult,'errors'> & {...}
- Fix build-esbuild non-watch return to use extendedBuildOpts not buildOpts
- Remove debug console.log('hello world!') from js-page/client.js example
- Fix missing comma in .claude/settings.local.json

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: bcomnes

.claude/settings.local.json

@@ -1,11 +1,13 @@
 {
   "permissions": {
     "allow": [
-      "Bash(node --test:*)"
+      "Bash(node --test:*)",
       "WebFetch(domain:github.com)",
       "WebFetch(domain:raw.githubusercontent.com)",
       "Bash(gh repo view:*)",
-      "Bash(gh api:*)"
+      "Bash(gh api:*)",
+      "mcp__mcp-server-github__add_reply_to_pull_request_comment",
+      "mcp__mcp-server-github__pull_request_read"
     ]
   }
 }

examples/basic/src/js-page/client.js

@@ -1,3 +1 @@
 console.log('This client script runs on the js page')
-
-console.log('hello world!')

index.js

@@ -10,9 +10,10 @@
  * @import { PageInfo, TemplateInfo } from './lib/identify-pages.js'
  * @import { PageData } from './lib/build-pages/page-data.js'
  * @import { BuildOptions, BuildContext, BuildResult } from 'esbuild'
- * @import { BuildPagesOpts, PageBuildStepResult } from './lib/build-pages/index.js'
+ * @import { PageBuildStepResult } from './lib/build-pages/index.js'
 */
 import { once } from 'events'
+import { cpus } from 'os'
 import assert from 'node:assert'
 import chokidar from 'chokidar'
 import { basename, relative, resolve } from 'node:path'
@@ -30,7 +31,7 @@ import { getCopyGlob, buildStatic } from './lib/build-static/index.js'
 import { getCopyDirs, buildCopy } from './lib/build-copy/index.js'
 import { builder } from './lib/builder.js'
 import { buildPages } from './lib/build-pages/index.js'
-import { identifyPages } from './lib/identify-pages.js'
+import { identifyPages, globalVarsNames, globalDataNames, esbuildSettingsNames, markdownItSettingsNames, templateSuffixes } from './lib/identify-pages.js'
 import { buildEsbuild } from './lib/build-esbuild/index.js'
 import { ensureDest } from './lib/helpers/ensure-dest.js'
 import { resolveVars } from './lib/build-pages/resolve-vars.js'
@@ -91,6 +92,8 @@ import { DomStackAggregateError } from './lib/helpers/dom-stack-aggregate-error.
  * @typedef {PageData<T, U, V>} PageData
  */
 
+const MAX_CONCURRENCY = Math.min(cpus().length, 24)
+
 const DEFAULT_IGNORES = /** @type {const} */ ([
   '.*',
   'coverage',
@@ -101,11 +104,6 @@ const DEFAULT_IGNORES = /** @type {const} */ ([
   'yarn.lock',
 ])
 
-const globalVarsNames = new Set(['global.vars.ts', 'global.vars.mts', 'global.vars.cts', 'global.vars.js', 'global.vars.mjs', 'global.vars.cjs'])
-const globalDataNames = new Set(['global.data.ts', 'global.data.mts', 'global.data.cts', 'global.data.js', 'global.data.mjs', 'global.data.cjs'])
-const esbuildSettingsNames = new Set(['esbuild.settings.ts', 'esbuild.settings.mts', 'esbuild.settings.cts', 'esbuild.settings.js', 'esbuild.settings.mjs', 'esbuild.settings.cjs'])
-const markdownItSettingsNames = new Set(['markdown-it.settings.ts', 'markdown-it.settings.mts', 'markdown-it.settings.cts', 'markdown-it.settings.js', 'markdown-it.settings.mjs', 'markdown-it.settings.cjs'])
-const templateSuffixes = ['.template.ts', '.template.mts', '.template.cts', '.template.js', '.template.mjs', '.template.cjs']
 
 /**
  * Find transitive ESM dependencies of a file.
@@ -115,7 +113,8 @@ const templateSuffixes = ['.template.ts', '.template.mts', '.template.cts', '.te
 async function findDepsOf (filepath) {
   try {
     return await findDeps(filepath)
-  } catch {
+  } catch (err) {
+    console.warn(`Warning: could not resolve deps of ${filepath}:`, err instanceof Error ? err.message : err)
     return []
   }
 }
@@ -154,7 +153,7 @@ async function buildWatchMaps (siteData) {
       if (!layoutDepMap.has(dep)) layoutDepMap.set(dep, new Set())
       layoutDepMap.get(dep)?.add(layout.layoutName)
     }
-  }, { concurrency: 8 })
+  }, { concurrency: MAX_CONCURRENCY })
 
   // Build layoutPageMap, pageFileMap, and pageDepMap by resolving each page's layout var
   // and static dep analysis of its page file and page.vars file.
@@ -164,8 +163,8 @@ async function buildWatchMaps (siteData) {
     pageFileMap.set(pageInfo.pageFile.filepath, pageInfo)
     if (pageInfo.pageVars) pageFileMap.set(pageInfo.pageVars.filepath, pageInfo)
 
-    const pageVars = /** @type {Record<string, any>} */ (await resolveVars({ varsPath: pageInfo.pageVars?.filepath }).catch(() => ({})))
-    const layoutName = /** @type {string} */ (pageVars['layout'] ?? 'root')
+    const pageVars = await resolveVars({ varsPath: pageInfo.pageVars?.filepath }).catch(() => ({}))
+    const layoutName = String((/** @type {Record<string, any>} */ (pageVars))['layout'] ?? 'root')
 
     if (!layoutPageMap.has(layoutName)) layoutPageMap.set(layoutName, new Set())
     layoutPageMap.get(layoutName)?.add(pageInfo)
@@ -180,7 +179,7 @@ async function buildWatchMaps (siteData) {
         pageDepMap.get(dep)?.add(pageInfo)
       }
     }
-  }, { concurrency: 8 })
+  }, { concurrency: MAX_CONCURRENCY })
 
   // Build templateDepMap via static dep analysis of each template file
   await pMap(siteData.templates, async (templateInfo) => {
@@ -189,7 +188,7 @@ async function buildWatchMaps (siteData) {
       if (!templateDepMap.has(dep)) templateDepMap.set(dep, new Set())
       templateDepMap.get(dep)?.add(templateInfo)
     }
-  }, { concurrency: 8 })
+  }, { concurrency: MAX_CONCURRENCY })
 
   return { layoutDepMap, layoutPageMap, pageFileMap, layoutFileMap, pageDepMap, templateDepMap }
 }
@@ -298,12 +297,12 @@ export class DomStack {
      * @param {Set<TemplateInfo>} [templateFilter]
      */
     const runPageBuild = async (pageFilter, templateFilter) => {
-      /** @type {BuildPagesOpts} */
-      const buildPagesOpts = {}
-      if (pageFilter) buildPagesOpts.pageFilterPaths = [...pageFilter].map(p => p.pageFile.filepath)
-      if (templateFilter) buildPagesOpts.templateFilterPaths = [...templateFilter].map(t => t.templateFile.filepath)
+      /** @type {DomStackOpts} */
+      const buildOpts = { ...opts }
+      if (pageFilter) buildOpts.pageFilterPaths = [...pageFilter].map(p => p.pageFile.filepath)
+      if (templateFilter) buildOpts.templateFilterPaths = [...templateFilter].map(t => t.templateFile.filepath)
       try {
-        const pageBuildResults = await buildPages(src, dest, siteData, opts, buildPagesOpts)
+        const pageBuildResults = await buildPages(src, dest, siteData, buildOpts)
 
         buildLogger(pageBuildResults)
         return pageBuildResults
@@ -482,28 +481,28 @@ export class DomStack {
       // buildEsbuild() in the main process and passed to esbuild as `define` substitutions.
       // esbuild's own watcher does NOT track global.vars as an input, so any change could
       // affect bundle output and requires restarting esbuild with fresh `define` values.
-      if (globalVarsNames.has(fileName)) {
+      if (globalVarsNames.includes(fileName)) {
         console.log('global.vars changed, running full rebuild...')
         await fullRebuild()
         return
       }
 
       // 2. global.data.* — data aggregation change, rebuild all pages
-      if (globalDataNames.has(fileName)) {
+      if (globalDataNames.includes(fileName)) {
         console.log('global.data changed, rebuilding all pages...')
         runPageBuild().catch(errorLogger)
         return
       }
 
       // 3. esbuild.settings.* — full esbuild context restart + all pages
-      if (esbuildSettingsNames.has(fileName)) {
+      if (esbuildSettingsNames.includes(fileName)) {
         console.log('esbuild.settings changed, restarting esbuild...')
         await fullRebuild()
         return
       }
 
       // 4. markdown-it.settings.* — rebuild all .md pages only (rendering change)
-      if (markdownItSettingsNames.has(fileName)) {
+      if (markdownItSettingsNames.includes(fileName)) {
         const mdPages = new Set(siteData.pages.filter(p => p.type === 'md'))
         logRebuildTree(fileName, mdPages)
         runPageBuild(mdPages).catch(errorLogger)

lib/build-esbuild/index.js

@@ -297,7 +297,7 @@ export async function buildEsbuild (src, dest, siteData, opts, watchOpts = {}) {
       report: {
         buildResults,
         outputMap,
-        buildOpts,
+        buildOpts: extendedBuildOpts,
       },
     }
   } catch (err) {

lib/build-pages/index.js

@@ -48,34 +48,27 @@ const __dirname = import.meta.dirname
  */
 
 /**
-  * @typedef {Omit<PageBuildStepResult, 'errors'> & {
-  *   errors: {error: Error, errorData?: object}[]
-  * }} WorkerBuildStepResult
+  * @typedef {object} WorkerBuildStepResult
+  * @property {'page'} type
+  * @property {PageBuilderReport} report
+  * @property {{error: Error, errorData?: object}[]} errors
+  * @property {import('../builder.js').BuildStepWarnings} warnings
  */
 
 export { pageBuilders }
 
-/**
- * Serializable version of build options passed through workerData.
- * Sets are not structured-clone serializable so we use filepath arrays.
- * @typedef {object} BuildPagesOpts
- * @property {string[]} [pageFilterPaths] - Only build pages whose pageFile.filepath is in this array
- * @property {string[]} [templateFilterPaths] - Only build templates whose templateFile.filepath is in this array
- */
-
 /**
  * Page builder glue. Most of the magic happens in the builders.
  * @param {string} src
  * @param {string} dest
  * @param {SiteData} siteData
- * @param {DomStackOpts} [_opts]
- * @param {BuildPagesOpts} [buildPagesOpts]
+ * @param {DomStackOpts} [opts]
  * @returns {Promise<PageBuildStepResult>}
  */
-export function buildPages (src, dest, siteData, _opts, buildPagesOpts = {}) {
+export function buildPages (src, dest, siteData, opts = {}) {
   return new Promise((resolve, reject) => {
     const worker = new Worker(join(__dirname, 'worker.js'), {
-      workerData: { src, dest, siteData, buildPagesOpts },
+      workerData: { src, dest, siteData, opts },
     })
 
     worker.once('message', message => {
@@ -114,14 +107,14 @@ export function buildPages (src, dest, siteData, _opts, buildPagesOpts = {}) {
  * All layouts, variables and page builders need to resolve in here
  * so that it can be run more than once, after the source files change.
  *
-  * @type {(...args: [...Parameters<PageBuildStep>, BuildPagesOpts?]) => Promise<WorkerBuildStepResult>} WorkerBuildStep
+  * @type {(...args: Parameters<PageBuildStep>) => Promise<WorkerBuildStepResult>} WorkerBuildStep
  */
-export async function buildPagesDirect (src, dest, siteData, _opts, buildPagesOpts = {}) {
-  const pageFilterPaths = buildPagesOpts.pageFilterPaths
-    ? new Set(buildPagesOpts.pageFilterPaths)
+export async function buildPagesDirect (src, dest, siteData, opts = {}) {
+  const pageFilterPaths = opts.pageFilterPaths
+    ? new Set(opts.pageFilterPaths)
     : null
-  const templateFilterPaths = buildPagesOpts.templateFilterPaths
-    ? new Set(buildPagesOpts.templateFilterPaths)
+  const templateFilterPaths = opts.templateFilterPaths
+    ? new Set(opts.templateFilterPaths)
     : null
 
   /** @type {WorkerBuildStepResult} */

lib/build-pages/resolve-vars.js

@@ -5,7 +5,7 @@
  * @param {string} [params.varsPath] - Path to the file containing the variables.
  * @param {object} [params.resolveVars] - Any variables you want passed to the reolveFunction.
  * @param {string} [params.key='default'] - The key to extract from the imported module. Default: 'default'
- * @returns {Promise<object|function>} - Returns the resolved variables. If the imported variable is a function, it executes and returns its result. Otherwise, it returns the variable directly.
+ * @returns {Promise<object>} - Returns the resolved variables. If the imported variable is a function, it executes and returns its result. Otherwise, it returns the variable directly.
  */
 export async function resolveVars ({
   varsPath,

lib/build-pages/worker.js

@@ -3,10 +3,10 @@ import { buildPagesDirect } from './index.js'
 
 async function run () {
   if (!parentPort) throw new Error('parentPort returned null')
-  const { src, dest, siteData, buildPagesOpts } = workerData
+  const { src, dest, siteData, opts } = workerData
   let results
   try {
-    results = await buildPagesDirect(src, dest, siteData, {}, buildPagesOpts)
+    results = await buildPagesDirect(src, dest, siteData, opts)
     parentPort.postMessage(results)
   } catch (err) {
     console.dir(results, { colors: true, depth: 999 })

lib/builder.js

@@ -51,6 +51,8 @@ import { ensureDest } from './helpers/ensure-dest.js'
  * @property {string[]|undefined} [target=[]] - Array of target strings to pass to esbuild
  * @property {boolean|undefined} [buildDrafts=false] - Build draft files with the published:false variable
  * @property {string[]|undefined} [copy=[]] - Array of paths to copy their contents into the dest directory
+ * @property {string[]|undefined} [pageFilterPaths] - Internal: only build pages whose pageFile.filepath is in this array
+ * @property {string[]|undefined} [templateFilterPaths] - Internal: only build templates whose templateFile.filepath is in this array
  */
 
 /**

lib/identify-pages.js

@@ -70,34 +70,36 @@ const globalClientNames = [
   'global.client.mjs', 'global.client.cjs'
 ]
 
-const globalVarsNames = nodeHasTS
+export const globalVarsNames = nodeHasTS
   ? [
       'global.vars.ts', 'global.vars.mts', 'global.vars.cts',
       'global.vars.js', 'global.vars.mjs', 'global.vars.cjs'
     ]
   : ['global.vars.js', 'global.vars.mjs', 'global.vars.cjs']
 
-const globalDataNames = nodeHasTS
+export const globalDataNames = nodeHasTS
   ? [
       'global.data.ts', 'global.data.mts', 'global.data.cts',
       'global.data.js', 'global.data.mjs', 'global.data.cjs'
     ]
   : ['global.data.js', 'global.data.mjs', 'global.data.cjs']
 
-const esbuildSettingsNames = nodeHasTS
+export const esbuildSettingsNames = nodeHasTS
   ? [
       'esbuild.settings.ts', 'esbuild.settings.mts', 'esbuild.settings.cts',
       'esbuild.settings.js', 'esbuild.settings.mjs', 'esbuild.settings.cjs'
     ]
   : ['esbuild.settings.js', 'esbuild.settings.mjs', 'esbuild.settings.cjs']
 
-const markdownItSettingsNames = nodeHasTS
+export const markdownItSettingsNames = nodeHasTS
   ? [
       'markdown-it.settings.ts', 'markdown-it.settings.mts', 'markdown-it.settings.cts',
       'markdown-it.settings.js', 'markdown-it.settings.mjs', 'markdown-it.settings.cjs'
     ]
   : ['markdown-it.settings.js', 'markdown-it.settings.mjs', 'markdown-it.settings.cjs']
 
+export const templateSuffixes = templateSuffixs
+
 /**
  * Shape the file walker object
  *