From 1cc4e4625e01e11c3b73171d5d20767ceef002c7 Mon Sep 17 00:00:00 2001
From: iris <iris@hyperhive.local>
Date: Sat, 12 Sep 2026 12:07:03 +0200
Subject: [PATCH] swarm-ui: trim build.mjs's top comment under the 30-line
 convention

mara flagged (PR #4297) that the comment-block lint doesn't catch this
file at all -- check-comment-blocks.sh (and check-issue-refs.sh) scope
to a fixed git ls-files extension list that omits .mjs. That's a real
gap (dashboard/build.mjs already has a 49-line block, pre-existing),
tracked separately -- but the fix here is to just respect the 30-line
convention regardless of whether the lint enforces it on this
extension. Cut the redundant per-file output-layout table (the code
below already names every output path) and kept only the genuinely
non-obvious decisions -- no content lost, verified against a plain awk
run of the lint's own line-counting logic.
---
 frontend/packages/swarm-ui/build.mjs | 83 +++++++++-------------------
 1 file changed, 25 insertions(+), 58 deletions(-)

diff --git a/frontend/packages/swarm-ui/build.mjs b/frontend/packages/swarm-ui/build.mjs
index f14bb7da..251430cd 100644
--- a/frontend/packages/swarm-ui/build.mjs
+++ b/frontend/packages/swarm-ui/build.mjs
@@ -1,66 +1,33 @@
-// esbuild build for @hive/swarm-ui (project-bootstrap scope). Output
-// layout (`dist/`):
+// esbuild build for @hive/swarm-ui (project-bootstrap scope). Bundles
+// main.tsx + its companion CSS, theme.css, and swarm-ui.css into
+// `dist/static/`, content-hashed (`[name]-[hash]`) so a redeploy's new
+// bundle gets a new URL, then rewrites those real URLs into index.html
+// and sw.js. See each output file's own name in the code below for what
+// it's for — not repeated here to avoid this comment drifting out of
+// sync with the actual build steps.
 //
-//   dist/index.html              served at GET / — its asset <link>/
-//                                 <script> URLs are rewritten below to the
-//                                 real hashed filenames esbuild picked
-//   dist/static/main-<hash>.js   served at /static/main-<hash>.js (ESM
-//                                 bundle, Preact + wouter-preact)
-//   dist/static/main-<hash>.js.map  source map sibling
-//   dist/static/main-<hash>.css  every component's own `import
-//                                 './Foo.css'` (Shell.css, Panel.css, …),
-//                                 folded by esbuild into one companion
-//                                 output alongside main-<hash>.js — no
-//                                 separate build step, this falls out of
-//                                 bundling main.tsx with `bundle: true`
-//   dist/static/colors.css       served at /static/colors.css — the ONE
-//                                 static asset deliberately left UNHASHED:
-//                                 nix/host-modules/swarm-ui.nix's stylix
-//                                 theming swaps this exact fixed path via
-//                                 an `= /static/colors.css` nginx location
-//                                 override, with no npm/esbuild rebuild
-//                                 involved. Hashing it would silently break
-//                                 that swap (the override would stop
-//                                 matching anything, and a themed host
-//                                 would revert to the default palette). See
-//                                 `colors.css`'s own top comment.
-//   dist/static/theme-<hash>.css      served at /static/theme-<hash>.css
-//   dist/static/swarm-ui-<hash>.css   served at /static/swarm-ui-<hash>.css
-//                                 — just the shared base reset now (@import
-//                                 resolved from @hive/shared), NOT
-//                                 component styles
-//   dist/manifest.webmanifest    served at /manifest.webmanifest (PWA)
-//   dist/sw.js                   served at /sw.js (PWA) — plain JS, no
-//                                 esbuild pass needed (see its own top
-//                                 comment for why); its `CACHE_VERSION`
-//                                 placeholder and shell-asset URLs are
-//                                 rewritten below, same as index.html.
-//                                 Filename itself stays fixed/unhashed —
-//                                 the browser polls this exact URL to
-//                                 detect a SW update, hashing it would
-//                                 make every deploy register as a brand
-//                                 new, unrelated worker.
+// `colors.css` is the ONE static asset deliberately left UNHASHED, at a
+// fixed `dist/static/colors.css`: nix/host-modules/swarm-ui.nix's stylix
+// theming swaps that exact path via an `= /static/colors.css` nginx
+// location override, no npm/esbuild rebuild involved. Hashing it would
+// silently break that swap. See `colors.css`'s own top comment.
 //
-// main/theme/swarm-ui's filenames are content-hashed so a redeploy's new
-// bundle gets a new URL — nginx's Cache-Control (a follow-up, host-side)
-// can then mark them `immutable, max-age=1y` for real, instead of caching
-// a fixed URL that silently serves stale bytes after a deploy changes the
-// nix store path underneath it.
+// `dist/sw.js` keeps its own fixed/unhashed filename too — the browser
+// polls this exact URL to detect a SW update, hashing it would make
+// every deploy register as a brand new worker. Its `CACHE_VERSION`
+// placeholder and shell-asset URLs get rewritten below, same as
+// index.html's.
 //
-// PWA icons (icon-192.png/icon-512.png/icon-512-maskable.png) are NOT
-// produced here — like favicon.svg, they're rasterized from
-// branding/*.svg and copied in by nix/packages/swarm-ui.nix's
-// installPhase, outside the npm tree this script builds. A plain `npm
-// run build` here has no `/icon-*.png`, same as it's always had no
-// `/favicon.svg`.
+// PWA icons are NOT produced here — like favicon.svg, they're
+// rasterized from branding/*.svg and copied in by
+// nix/packages/swarm-ui.nix's installPhase, outside the npm tree this
+// script builds.
 //
 // Not yet wired into any Rust binary's `ServeDir` — swarm-controller
-// only serves `/health` today (see swarm-controller/README.md); this
-// just makes `dist/` buildable so nix/packages/swarm-ui.nix has
-// something to package. `.tsx` → JS: esbuild transpiles TypeScript
-// natively (types stripped, not checked) — run `npm run typecheck`
-// (plain `tsc --noEmit`) separately for real type errors; not yet
-// wired into CI.
+// only serves `/health` today; this just makes `dist/` buildable so
+// nix/packages/swarm-ui.nix has something to package. `.tsx` → JS:
+// esbuild transpiles TypeScript natively (types stripped, not checked)
+// — run `npm run typecheck` separately for real type errors.
 
 import { build } from "esbuild";
 import { mkdirSync, rmSync, readFileSync, writeFileSync } from "node:fs";