tosijs-ui 1.6.21 → 1.7.0-beta.1

package/dist/doc-system/site/orchestrator.js

@@ -12,31 +12,80 @@ the icon system here would put src/icon-data.ts into `bun --watch`'s graph and
 cause an endless rebuild loop.
 */
 import * as path from 'path';
-import { existsSync, mkdirSync } from 'fs';
+import { existsSync, mkdirSync, unlinkSync } from 'fs';
+import { tmpdir } from 'os';
 import { gzipSync } from 'zlib';
-import { $ } from 'bun';
+import { $, spawn } from 'bun';
 import { extractDocs } from './docs';
 import { checkExamples, formatExampleProblems } from './check-examples';
 import { ensureSections } from './sections';
 import { generateLlmsTxt } from './make-llms-txt';
 import { generateSite } from './generate-site';
 import { findOutputDirOverlap } from './output-guard';
-import { buildEpub } from './epub';
+import { tjsEditorExternal, tjsEditorLeakedAsExternal, classicScriptSyntaxErrorInChild, } from './bundle-guard';
 // Module specifiers contain regex metacharacters (`/`, `.`, `@`, …), so escape
 // before interpolating into the require-shim detector below.
-const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-// Externalize the tjs CodeMirror editor extension ONLY when tjs-lang isn't
-// installed — otherwise it's bundled in so it shares the editor's CodeMirror
-// instance (see the `external` comment in buildSite). Returns [] when present.
-function tjsEditorExternal(root) {
+/** Give up on a hung ePub child rather than wedge the dev server's rebuild. */
+const EPUB_TIMEOUT_MS = 120_000;
+/**
+ * Run buildEpub() in a child process.
+ *
+ * buildEpub drives happy-dom (HTML→XHTML for every chapter) and @resvg/resvg-js
+ * (cover raster) — both native, both retaining — and it runs on EVERY dev rebuild,
+ * so in-process it strands memory in a watch process that lives for days. The child
+ * hands it all back on exit. If it hangs we kill it, and if it fails we warn: the
+ * ePub is a side artifact, so neither should block the page you're trying to look at.
+ *
+ * Only the data buildEpub reads is forwarded — SiteConfig also carries functions
+ * (llmsTxt, libraryBuild, prebuild) that don't survive JSON.
+ */
+async function buildEpubInChild(config, opts) {
+    // Resolve the sibling relative to THIS module so it works both in-repo (.ts)
+    // and when shipped (compiled .js) — same trick as generate-css below.
+    const cliTs = `${import.meta.dir}/epub-cli.ts`;
+    const cli = existsSync(cliTs) ? cliTs : `${import.meta.dir}/epub-cli.js`;
+    const payload = {
+        config: {
+            basePath: config.basePath,
+            baseUrl: config.baseUrl,
+            book: config.book,
+            docsJson: config.docsJson,
+            favicon: config.favicon,
+            lang: config.lang,
+            name: config.name,
+            outputDir: config.outputDir,
+        },
+        opts,
+    };
+    const payloadPath = path.join(tmpdir(), `tosijs-epub-${process.pid}.json`);
+    await Bun.write(payloadPath, JSON.stringify(payload));
+    const child = spawn(['bun', cli, payloadPath], {
+        stdout: 'inherit',
+        stderr: 'inherit',
+    });
+    const killer = setTimeout(() => {
+        console.warn(`⚠️  epub build exceeded ${EPUB_TIMEOUT_MS / 1000}s — killing it. The site is\n` + `    fine; the .epub may be stale.`);
+        child.kill();
+    }, EPUB_TIMEOUT_MS);
     try {
-        Bun.resolveSync('tjs-lang/editors/codemirror', root);
-        return [];
+        const code = await child.exited;
+        if (code !== 0) {
+            console.warn(`⚠️  epub build failed (exit ${code}). The site is fine; the .epub may be stale.`);
+        }
     }
-    catch {
-        return ['tjs-lang/editors/codemirror'];
+    finally {
+        clearTimeout(killer);
+        try {
+            unlinkSync(payloadPath);
+        }
+        catch {
+            // already gone — fine
+        }
     }
 }
+// Module specifiers contain regex metacharacters (`/`, `.`, `@`, …), so escape
+// before interpolating into the require-shim detector below.
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 export async function buildSite(config) {
     const PROJECT_ROOT = './';
     const PUBLIC = path.resolve(PROJECT_ROOT, config.outputDir ?? 'docs');
@@ -97,7 +146,8 @@ export async function buildSite(config) {
         }
     }
     // Copy static-asset dirs into the web root.
-    const staticDirs = config.staticDirs ?? (existsSync('demo/static') ? ['demo/static'] : ['static']);
+    const staticDirs = config.staticDirs ??
+        (existsSync('demo/static') ? ['demo/static'] : ['static']);
     for (const dir of staticDirs) {
         if (existsSync(dir))
             await $ `cp -R ${dir}/. ${PUBLIC}`.text();
@@ -142,36 +192,58 @@ export async function buildSite(config) {
     // consumer supplies (e.g. via staticDirs or an absolute URL).
     const scriptName = (config.scriptUrl ?? '/iife.js').replace(/^\//, '');
     if (config.bundleEntry) {
-        const result = await Bun.build({
-            entrypoints: [config.bundleEntry],
-            outdir: DIST,
-            sourcemap: 'linked',
-            format: 'iife',
-            minify: true,
-            naming: scriptName,
-            // tjs-lang's TRANSPILER (browser bundles) is dynamically import()'d at
-            // runtime (same-origin `/tjs/` copy, else CDN), so keep it out of the bundle.
-            //
-            // `tjs-lang/editors/codemirror` (the CodeMirror language + autocomplete) is
-            // different: it MUST share the editor's CodeMirror instance, so it has to be
-            // bundled IN — a separately loaded copy carries its own `@codemirror/state`
-            // and silently no-ops. So we do NOT externalize it *when tjs-lang is
-            // installed*. But tjs-lang is an OPTIONAL peer; if it's absent, bundling would
-            // fail to resolve, so we externalize it in that case (the runtime import then
-            // no-ops to plain TS highlighting — graceful degradation).
-            external: [
-                'tjs-lang/browser',
-                'tjs-lang/browser/from-ts',
-                ...tjsEditorExternal(PROJECT_ROOT),
-                ...(config.bundleExternals ?? []),
-            ],
-        });
-        if (!result.success) {
+        // tjs-lang's TRANSPILER (browser bundles) is dynamically import()'d at
+        // runtime (same-origin `/tjs/` copy, else CDN), so keep it out of the bundle.
+        //
+        // `tjs-lang/editors/codemirror` (the CodeMirror language + autocomplete) is
+        // different: it MUST share the editor's CodeMirror instance, so it has to be
+        // bundled IN — a separately loaded copy carries its own `@codemirror/state`
+        // and silently no-ops. So we do NOT externalize it *when tjs-lang is
+        // installed*. But tjs-lang is an OPTIONAL peer; if it's absent, bundling would
+        // fail to resolve, so we externalize it in that case (the runtime import then
+        // no-ops to plain TS highlighting — graceful degradation).
+        //
+        // NB: bare `'tjs-lang'` must NOT appear here. Externals are PREFIX matches, so
+        // it would silently externalize tjs-lang/editors/codemirror along with it.
+        const externals = [
+            'tjs-lang/browser',
+            'tjs-lang/browser/from-ts',
+            ...tjsEditorExternal(PROJECT_ROOT),
+            ...(config.bundleExternals ?? []),
+        ];
+        // Bundle in a CHILD PROCESS, not via Bun.build().
+        //
+        // Bun.build() never gives back the bundler's native arena: measured at ~9MB
+        // of RSS per call and rising, monotonic, with no plateau (40 sequential
+        // builds of one real entry = +367MB, still climbing ~5MB/build at the end),
+        // while the JS heap stays flat — so it is invisible to Bun.gc() and to any
+        // heap profiler. devServer() calls this once per rebuild in a process that
+        // lives for DAYS, so it compounds: a ~2-day watch session reached 136GB RSS
+        // and took the machine down with it. Filed as oven-sh/bun#34053.
+        //
+        // The CLI does identical work in a child whose memory the OS reclaims on
+        // exit: the same 15 bundles leave the parent +0.5MB instead of +192MB.
+        // Keep these flags in sync with the Bun.build() options they replace.
+        const bundle = spawn([
+            'bun',
+            'build',
+            config.bundleEntry,
+            '--outdir',
+            DIST,
+            '--sourcemap=linked',
+            '--format=iife',
+            '--minify',
+            '--entry-naming',
+            scriptName,
+            ...externals.flatMap((ext) => ['--external', ext]),
+        ], { stdout: 'inherit', stderr: 'inherit' });
+        if ((await bundle.exited) !== 0) {
             console.error('bundle build failed');
-            for (const message of result.logs)
-                console.error(message);
             return false;
         }
+        await $ `cp ${DIST}/${scriptName} ${PUBLIC}`.text();
+        const bundleFile = await Bun.file(`${DIST}/${scriptName}`).arrayBuffer();
+        const bundleJs = Buffer.from(bundleFile).toString('utf8');
         // Warn only when an external actually compiled to a synchronous require()
         // shim, which throws at module-eval ("Dynamic require of … is not
         // supported"). That only happens for a *static* `import x from 'ext'`. A
@@ -180,23 +252,37 @@ export async function buildSite(config) {
         // stay silent. The config alone can't tell the two apart; the emitted
         // bundle can, so we inspect the actual output.
         if (config.bundleExternals && config.bundleExternals.length > 0) {
-            const js = (await Promise.all(result.outputs
-                .filter((o) => o.kind === 'entry-point' || o.path.endsWith('.js'))
-                .map((o) => o.text()))).join('\n');
-            const broken = config.bundleExternals.filter((ext) => new RegExp(`(?:__require|\\brequire)\\(\\s*["'\`]${escapeRegExp(ext)}["'\`]`).test(js));
+            const broken = config.bundleExternals.filter((ext) => new RegExp(`(?:__require|\\brequire)\\(\\s*["'\`]${escapeRegExp(ext)}["'\`]`).test(bundleJs));
             if (broken.length > 0) {
                 console.warn(`⚠️  bundleExternals compiled to a synchronous require() shim that throws at runtime (${broken.join(', ')}). Reference these via a dynamic import() (kept async by the bundler)\n` +
                     `    or an importmap, not a static import.`);
             }
         }
-        await $ `cp ${DIST}/${scriptName} ${PUBLIC}`.text();
-        const bundleFile = await Bun.file(`${DIST}/${scriptName}`).arrayBuffer();
-        // import.meta is illegal in a classic <script> — if it survived bundling
-        // (a branch the bundler couldn't eliminate) the IIFE will SyntaxError.
-        if (Buffer.from(bundleFile).toString('utf8').includes('import.meta')) {
-            console.warn(`⚠️  ${scriptName} contains \`import.meta\`, which is a SyntaxError in a classic <script>.\n` +
-                `    A dependency referenced it in a branch the bundler couldn't drop — mark that dep external\n` +
-                `    (+ importmap) or choose a browser-only entry point.`);
+        // The IIFE must parse as a classic <script>. `import.meta` is the usual way it
+        // doesn't (a branch the bundler couldn't eliminate) — and it's a SyntaxError, so
+        // the whole bundle fails to evaluate and the page never hydrates. Compile it
+        // (without running it) rather than grepping: the substring also occurs inside
+        // string literals — acorn's error messages contain it — which made the old grep
+        // fire on every build while the bundle was fine.
+        const syntaxError = await classicScriptSyntaxErrorInChild(`${DIST}/${scriptName}`);
+        if (syntaxError) {
+            console.error(`⚠️  ${scriptName} does not parse as a classic <script>: ${syntaxError}\n` +
+                `    The page will not hydrate. If a dependency pulled in \`import.meta\`, mark it\n` +
+                `    external (+ importmap) or choose a browser-only entry point.`);
+            return false;
+        }
+        // tjs-lang's CodeMirror extension MUST be bundled, not externalized — a separate
+        // copy carries its own @codemirror/state and silently no-ops (tjs highlighting and
+        // autocomplete just stop working, with no error anywhere). If it was externalized,
+        // the bundler leaves its specifier behind. Failing the build is the only way this
+        // gets noticed; every test lane stays green when it regresses.
+        if (tjsEditorExternal(PROJECT_ROOT).length === 0 &&
+            tjsEditorLeakedAsExternal(bundleJs)) {
+            console.error(`⚠️  ${scriptName} externalized tjs-lang's CodeMirror extension instead of bundling it.\n` +
+                `    It must share the editor's single CodeMirror instance; a separately loaded copy\n` +
+                `    silently no-ops. Check the bundle's \`external\` list — entries are PREFIX matches,\n` +
+                `    so a bare 'tjs-lang' externalizes tjs-lang/editors/codemirror along with it.`);
+            return false;
         }
         const bundleGzip = gzipSync(Buffer.from(bundleFile));
         console.log(`${scriptName}: ${(bundleFile.byteLength / 1024).toFixed(1)}kb (${(bundleGzip.length / 1024).toFixed(1)}kb gzip)`);
@@ -319,7 +405,7 @@ export async function buildSite(config) {
     // the corpus and survives the `rm -rf <outputDir>` at the top of the NEXT build
     // (otherwise a dev rebuild would silently drop it). Cheap (~0.4s).
     if (config.epub) {
-        await buildEpub(config, typeof config.epub === 'object' ? config.epub : {});
+        await buildEpubInChild(config, typeof config.epub === 'object' ? config.epub : {});
     }
     console.timeEnd('build');
     return true;

package/dist/doc-system/site/site-config.d.ts

@@ -186,6 +186,16 @@ export interface SiteConfig {
     port?: number;
     /** extra dev-server watch paths (added to docPaths + bundleEntry dir). */
     watchPaths?: string[];
+    /**
+     * RSS ceiling (MB) for the dev server, default 4096. A watch process lives for
+     * days across thousands of rebuilds, so anything the build strands per rebuild
+     * compounds until the machine swaps itself to death. Past this, the server
+     * prints the growth-per-rebuild and exits rather than take the machine with it.
+     * Overridden by the DEV_MEMORY_LIMIT_MB env var. Raise it if a genuinely large
+     * build needs the headroom — but sustained growth per rebuild is a leak, not a
+     * ceiling that's too low.
+     */
+    memoryLimitMb?: number;
     /**
      * Enable the dev-server source read/write endpoints (`/__docstore/source`) that
      * back in-browser "edit page source". Local dev only — the dev server runs on