fix(build): frontend build determinism across line endings (DC-119) [glm-grade=A]
CI / Test & Lint (push) Canceled after 0s
CI / Security audit (push) Canceled after 0s

The deploy host showed phantom dist drift on every git pull: committed
dist bundles could not be reproduced on DNS2. Root cause (verified with
esbuild 0.25.12 probes): the production transform uses sourcemap:'both',
whose inline map base64-embeds RAW source bytes as sourcesContent — a CRLF
working copy (Windows dev, core.autocrlf=true) vs an LF checkout produces
different dist bytes and a different sw.js cache tag.

- build.js: normalizeSource (\r\n -> \n) on every source read (bundle
  inputs + sw.js read); exported + require.main guard so tests can import
  it without triggering a build
- .gitattributes: * text=auto eol=lf (git-layer kill of the CRLF vector)
  + binary exclusions; 9 CRLF-in-index asset files renormalized
- tests/build-determinism.test.js: 3-case pin (byte-identity after
  normalization, divergence pre-normalization, CR-strip contract) importing
  the ACTUAL normalizeSource from build.js
- package.json: declare jsdom devDependency — 2 committed test files
  require('jsdom') but it was never declared, so fresh-checkout
  npm test failed (it only passed where a stray ancestor node_modules
  happened to contain it)
- dist/features.js + sw.js: canonical deterministic rebuild
  (cache tag 3354f5fd96 -> d39ab69dd4)

Verified: status 54/54, API 2858/2858 (128 suites); CRLF-sim tree and LF
tree of same HEAD produce byte-identical dist artifacts (sha256-equal).
Judge: glm-5.3 cold round 1 = A, round 2 (post-fold) = A clean, 0 blocking.
This commit is contained in:
Hermes
2026-08-23 16:34:49 -07:00
parent 1744d1c86e
commit 4d97a11978
16 changed files with 3065 additions and 2319 deletions
+49 -17
View File
@@ -3,6 +3,12 @@ const path = require('path');
const crypto = require('crypto');
const esbuild = require('esbuild');
// DC-119: single source of truth for the CRLF->LF normalization applied to
// every source read before minification (see the long comment in build()).
// Exported so tests/build-determinism.test.js pins THE ACTUAL regex, not a
// re-implementation that would silently drift if this one changes.
const normalizeSource = (s) => s.replace(/\r\n/g, '\n');
const JS = (...parts) => path.join(__dirname, 'js', ...parts);
const DIST = path.join(__dirname, 'dist');
const INDEX_HTML = path.join(__dirname, 'index.html');
@@ -149,7 +155,20 @@ async function build() {
console.warn(` WARN: ${path.relative(__dirname, file)} not found, skipping`);
continue;
}
parts.push(fs.readFileSync(file, 'utf8'));
// DC-119: normalize CRLF -> LF before minifying. Root cause (verified
// empirically with esbuild 0.25.12 probes): the production transform
// uses sourcemap:'both', which base64-embeds the RAW source bytes as
// sourcesContent in the inline map — CR bytes survive into dist, so a
// CRLF working copy (Windows dev tree, core.autocrlf=true) and an LF
// checkout (DNS2) of the same commit produce different dist bytes and
// a different sw.js cache tag. With this normalization both are
// byte-identical (sha256-verified). Before it, every Linux rebuild of
// a Windows-committed bundle showed phantom drift on `git pull` in
// /opt/dashcaddy (the recurring "pre-pull drift" stashes — note those
// also contained minified-identifier renames, a second vector from
// esbuild version drift across the ^0.25.0 caret range, already
// pinned by package-lock.json).
parts.push(normalizeSource(fs.readFileSync(file, 'utf8')));
}
const concatenated = parts.join(';\n');
@@ -197,7 +216,11 @@ async function build() {
// the SW's activate handler wipes all older caches, so users never get
// stuck on stale precached bundles after a release.
function updateServiceWorkerCache() {
const sw = fs.readFileSync(SW_JS, 'utf8');
// DC-119: normalize on read — same rationale as the bundle sources above.
// A CRLF sw.js would otherwise keep its CR bytes through the regex
// replace, so the written sw.js (and its committed bytes) would differ
// per-platform even with an identical cache tag.
const sw = normalizeSource(fs.readFileSync(SW_JS, 'utf8'));
const hash = crypto.createHash('sha256');
for (const name of Object.keys(bundles)) {
hash.update(fs.readFileSync(path.join(DIST, name)));
@@ -214,20 +237,29 @@ function updateServiceWorkerCache() {
}
// Watch mode
if (process.argv.includes('--watch')) {
console.log(' Watching for changes...\n');
build();
// DC-119: only auto-run when invoked directly (`node build.js`). Requiring
// build.js as a module (as tests/build-determinism.test.js does, to pin the
// normalizeSource regex) must NOT trigger a full dist rebuild.
if (require.main === module) {
if (process.argv.includes('--watch')) {
console.log(' Watching for changes...\n');
build();
const jsDir = path.join(__dirname, 'js');
let debounce = null;
fs.watch(jsDir, { recursive: true }, (event, filename) => {
if (!filename || !filename.endsWith('.js')) return;
clearTimeout(debounce);
debounce = setTimeout(() => {
console.log(` Changed: ${filename}`);
build();
}, 200);
});
} else {
build();
const jsDir = path.join(__dirname, 'js');
let debounce = null;
fs.watch(jsDir, { recursive: true }, (event, filename) => {
if (!filename || !filename.endsWith('.js')) return;
clearTimeout(debounce);
debounce = setTimeout(() => {
console.log(` Changed: ${filename}`);
build();
}, 200);
});
} else {
build();
}
}
// DC-119: export for tests (normalizeSource is pinned by
// tests/build-determinism.test.js). build/bundles stay internal.
module.exports = { normalizeSource };