Harden build pipeline per review feedback

- Use sass-embedded default export for sass-loader implementation
- Move @babel/plugin-transform-runtime to plugins; add @babel/runtime dep
- Validate BUILD_THREAD_WORKERS; cap to CPU; add PRODUCTION_POOL_TIMEOUT_MS
- Handle watcher close errors under BUILD_WATCH_ONCE
- Parse BUILD_CACHE_COMPRESSION strictly; warn on invalid values
- Isolate webpack filesystem cache per variant (cache.name)
- Fail on missing build artifacts in copyFiles (dev CSS placeholders allowed)
- Make mkdir recursive for targetDir
- Strengthen CI webpack cache key with Node version and build.mjs hash
- Polish docs wording for Performance defaults

These changes address concrete reviewer findings to prevent runtime errors,
avoid cache collisions during parallel builds, stop silently missing
artifacts, and make builds/CI more predictable and auditable.

Author: PeterDaveHello

.github/copilot-instructions.md

@@ -30,8 +30,8 @@ Always reference these instructions first and fall back to search or bash comman
   - Affects only `.cache/webpack` size/speed; does not change final artifacts
 - BUILD_WATCH_ONCE (dev): When set, `npm run dev` runs a single build and exits (useful for timing)
 
-Performance defaults: esbuild is used for JS/CSS minification; dev injects CSS via style-loader,
-prod extracts CSS via MiniCssExtractPlugin; thread-loader is enabled by default in both dev and prod.
+Performance defaults: esbuild handles JS/CSS minification; in development CSS is injected via style-loader,
+in production CSS is extracted via MiniCssExtractPlugin; thread-loader is enabled by default in both dev and prod.
 
 ### Build Output Structure
 

.github/workflows/pre-release-build.yml

@@ -38,9 +38,9 @@ jobs:
           path: |
             .cache/webpack
             node_modules/.cache/webpack
-          key: ${{ runner.os }}-webpack-${{ hashFiles('**/package-lock.json') }}
+          key: ${{ runner.os }}-node20-webpack-${{ hashFiles('build.mjs') }}-${{ hashFiles('**/package-lock.json') }}
           restore-keys: |
-            ${{ runner.os }}-webpack-
+            ${{ runner.os }}-node20-webpack-
       - run: npm run build
 
       - uses: josStorer/get-current-time@v2

build.mjs

@@ -19,17 +19,43 @@ const isWatchOnce = !!process.env.BUILD_WATCH_ONCE
 // Cache compression control: default none; allow override via env
 const cacheCompressionEnv = process.env.BUILD_CACHE_COMPRESSION
 let cacheCompressionOption
-if (cacheCompressionEnv) {
-  const v = String(cacheCompressionEnv).toLowerCase()
-  if (v === '0' || v === 'false' || v === 'none') cacheCompressionOption = false
-  else if (v === 'brotli') cacheCompressionOption = 'brotli'
-  else cacheCompressionOption = 'gzip' // treat any truthy/unknown as gzip
+if (cacheCompressionEnv != null) {
+  const v = String(cacheCompressionEnv).trim().toLowerCase()
+  if (v === '' || v === '0' || v === 'false' || v === 'none') {
+    cacheCompressionOption = false
+  } else if (v === 'gzip' || v === 'brotli') {
+    cacheCompressionOption = v
+  } else {
+    console.warn(
+      `[build] Unknown BUILD_CACHE_COMPRESSION="${cacheCompressionEnv}", defaulting to no compression`,
+    )
+    cacheCompressionOption = false
+  }
 }
-const cpuCount = os.cpus()?.length || 1
-const envWorkers = process.env.BUILD_THREAD_WORKERS
+const cpuCountRaw = os.cpus()?.length
+const cpuCount = Number.isInteger(cpuCountRaw) && cpuCountRaw > 0 ? cpuCountRaw : 1
+const rawWorkers = process.env.BUILD_THREAD_WORKERS
   ? parseInt(process.env.BUILD_THREAD_WORKERS, 10)
   : undefined
-const threadWorkers = Number.isInteger(envWorkers) && envWorkers > 0 ? envWorkers : cpuCount
+let threadWorkers
+if (Number.isInteger(rawWorkers) && rawWorkers > 0) {
+  const maxWorkers = Math.max(1, cpuCount)
+  if (rawWorkers > maxWorkers) {
+    console.warn(
+      `[build] BUILD_THREAD_WORKERS=${rawWorkers} exceeds CPU count (${cpuCount}); capping to ${maxWorkers}`,
+    )
+  }
+  threadWorkers = Math.min(rawWorkers, maxWorkers)
+} else {
+  if (process.env.BUILD_THREAD_WORKERS) {
+    console.warn(
+      `[build] Invalid BUILD_THREAD_WORKERS="${process.env.BUILD_THREAD_WORKERS}", defaulting to CPU count (${cpuCount})`,
+    )
+  }
+  threadWorkers = cpuCount
+}
+// Thread-loader pool timeout constants
+const PRODUCTION_POOL_TIMEOUT_MS = 2000
 // Enable threads by default; allow disabling via BUILD_THREAD=0
 const enableThread = process.env.BUILD_THREAD === '0' ? false : true
 
@@ -52,7 +78,16 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
   ]
   if (isWithoutKatex) shared.push('./src/components')
 
-  const sassImpl = await import('sass-embedded')
+  // Use the default export from sass-embedded; sass-loader expects the implementation object
+  const { default: sassImpl } = await import('sass-embedded')
+
+  const variantId = [
+    isWithoutKatex ? 'no-katex' : 'with-katex',
+    isWithoutTiktoken ? 'no-tiktoken' : 'with-tiktoken',
+    minimal ? 'minimal' : 'full',
+    sourceBuildDir || outdir,
+    isProduction ? 'prod' : 'dev',
+  ].join('|')
 
   const compiler = webpack({
     entry: {
@@ -81,6 +116,7 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
     devtool: isProduction ? false : 'cheap-module-source-map',
     cache: {
       type: 'filesystem',
+      name: `webpack-${variantId}`,
       // default none; override via BUILD_CACHE_COMPRESSION=gzip|brotli
       compression: cacheCompressionOption ?? false,
       buildDependencies: {
@@ -164,7 +200,11 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
                     options: {
                       workers: threadWorkers,
                       // Ensure one-off dev build exits quickly
-                      poolTimeout: isProduction ? 2000 : isWatchOnce ? 0 : Infinity,
+                      poolTimeout: isProduction
+                        ? PRODUCTION_POOL_TIMEOUT_MS
+                        : isWatchOnce
+                        ? 0
+                        : Infinity,
                     },
                   },
                 ]
@@ -174,13 +214,9 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
               options: {
                 cacheDirectory: true,
                 cacheCompression: false,
-                presets: [
-                  '@babel/preset-env',
-                  {
-                    plugins: ['@babel/plugin-transform-runtime'],
-                  },
-                ],
+                presets: ['@babel/preset-env'],
                 plugins: [
+                  ['@babel/plugin-transform-runtime'],
                   [
                     '@babel/plugin-transform-react-jsx',
                     {
@@ -309,7 +345,11 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
   else {
     const watching = compiler.watch({}, (err, stats) => {
       callback(err, stats)
-      if (process.env.BUILD_WATCH_ONCE) watching.close(() => {})
+      if (process.env.BUILD_WATCH_ONCE) {
+        watching.close((closeErr) => {
+          if (closeErr) console.error('Error closing watcher:', closeErr)
+        })
+      }
     })
   }
 }
@@ -325,11 +365,23 @@ async function zipFolder(dir) {
 }
 
 async function copyFiles(entryPoints, targetDir) {
-  if (!fs.existsSync(targetDir)) await fs.mkdir(targetDir)
+  if (!fs.existsSync(targetDir)) await fs.mkdir(targetDir, { recursive: true })
   await Promise.all(
     entryPoints.map(async (entryPoint) => {
-      if (await fs.pathExists(entryPoint.src)) {
-        await fs.copy(entryPoint.src, `${targetDir}/${entryPoint.dst}`)
+      try {
+        if (await fs.pathExists(entryPoint.src)) {
+          await fs.copy(entryPoint.src, `${targetDir}/${entryPoint.dst}`)
+        } else {
+          // Skip missing CSS in development (placeholders will be created later)
+          const isCss = String(entryPoint.dst).endsWith('.css')
+          if (!isProduction || isCss) {
+            if (!isProduction && isCss) return
+          }
+          throw new Error(`Missing build artifact: ${entryPoint.src}`)
+        }
+      } catch (e) {
+        console.error('Copy failed:', entryPoint, e)
+        throw e
       }
     }),
   )

package.json

@@ -19,6 +19,7 @@
     "lint"
   ],
   "dependencies": {
+    "@babel/runtime": "^7.24.7",
     "@mozilla/readability": "^0.6.0",
     "@nem035/gpt-3-encoder": "^1.1.7",
     "@picocss/pico": "^1.5.13",