catalyst-core 1.0.1 → 1.0.2-canary.2

package/test/scripts/build.test.ts

@@ -0,0 +1,275 @@
+import { EventEmitter } from "node:events"
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { createRequire } from "node:module"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { PassThrough } from "node:stream"
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"
+
+import type themeModule from "../../src/cli/theme.js"
+
+// Required, the way build.js itself loads it, so v8 coverage sees one copy.
+const theme: typeof themeModule = createRequire(import.meta.url)("../../src/cli/theme.js")
+
+// build.js runs on import, so each test re-imports it against a throwaway app
+// with the preflight stubbed and spawn faked: every step "runs" by printing
+// the given output and exiting with the given code.
+vi.mock("../../src/scripts/preflight.js", () => ({
+    runStaticPreflightOrExit: () => {},
+    writeBuildInfo: () => {},
+}))
+
+// `spawnError` makes the step fail to start at all; `run` stands in for what
+// the step writes to disk.
+type Step = { output: string; code: number; spawnError?: Error; run?: () => void }
+const steps: Record<"server" | "client" | "manifest", Step> = {
+    server: { output: "", code: 0 },
+    client: { output: "", code: 0 },
+    manifest: { output: "", code: 0 },
+}
+
+vi.mock("child_process", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("child_process")>()
+    const spawn = (_cmd: string, args: string[]) => {
+        const name = args.includes("--ssr")
+            ? "server"
+            : args.some((arg) => arg.includes("generateOfflineManifest"))
+              ? "manifest"
+              : "client"
+        const child = Object.assign(new EventEmitter(), {
+            stdout: new PassThrough(),
+            stderr: new PassThrough(),
+        })
+        const step = steps[name]
+        setImmediate(() => {
+            if (step.spawnError) return child.emit("error", step.spawnError)
+            step.run?.()
+            child.stderr.write(step.output)
+            setImmediate(() => child.emit("close", step.code))
+        })
+        return child
+    }
+    return { ...actual, default: { ...actual, spawn }, spawn }
+})
+
+const plain = (text: string) => text.replace(theme.ANSI, "")
+
+let appDir: string
+let stderr: string
+let stdout: string
+let exitCode: Promise<number>
+const originalArgv = process.argv
+const originalPwd = process.env.PWD
+
+async function runBuild(argv: string[] = []) {
+    process.argv = [originalArgv[0], "build.js", ...argv]
+    let settle: (code: number) => void
+    exitCode = new Promise((resolve) => (settle = resolve))
+    let exited = false
+    // The first exit is the one under test; throwing stops build() there, and
+    // its top-level catch then calls exit again, which is ignored.
+    vi.spyOn(process, "exit").mockImplementation(((code: number) => {
+        if (exited) return undefined as never
+        exited = true
+        settle(code)
+        throw new Error("exit")
+    }) as never)
+    vi.resetModules()
+    await import("../../src/scripts/build.js")
+    return exitCode
+}
+
+beforeEach(() => {
+    appDir = mkdtempSync(path.join(tmpdir(), "catalyst-build-"))
+    mkdirSync(path.join(appDir, "config"))
+    writeFileSync(path.join(appDir, "config", "config.json"), JSON.stringify({ BUILD_OUTPUT_PATH: "build" }))
+    writeFileSync(path.join(appDir, "package.json"), JSON.stringify({ name: "fixture-app" }))
+    process.env.PWD = appDir
+    stderr = ""
+    vi.spyOn(process.stderr, "write").mockImplementation(((chunk: string) => {
+        stderr += String(chunk)
+        return true
+    }) as never)
+    stdout = ""
+    // Spinner lines go to stdout.write, the rest through console.log.
+    vi.spyOn(process.stdout, "write").mockImplementation(((chunk: string) => {
+        stdout += String(chunk)
+        return true
+    }) as never)
+    vi.spyOn(console, "log").mockImplementation((line: string) => {
+        stdout += `${String(line)}\n`
+    })
+    vi.spyOn(console, "error").mockImplementation(() => {})
+    for (const name of Object.keys(steps) as (keyof typeof steps)[]) steps[name] = { output: "", code: 0 }
+})
+
+afterEach(() => {
+    vi.restoreAllMocks()
+    process.argv = originalArgv
+    process.env.PWD = originalPwd
+    rmSync(appDir, { recursive: true, force: true })
+})
+
+describe("catalyst build failure output", () => {
+    it("reports both bundles when only one bundle's error is recognised", async () => {
+        steps.server = { output: "src/js/App.js:3:10: ERROR: Expected ';' but found 'x'\n", code: 1 }
+        steps.client = { output: "something the patterns do not know\n", code: 1 }
+
+        expect(await runBuild()).toBe(1)
+        const text = plain(stderr)
+        expect(text).toMatch(/Expected ';' but found 'x'/)
+        expect(text).toMatch(/The client bundle failed/)
+        expect(text).toMatch(/something the patterns do not know/)
+    })
+
+    it("shows the tail of a failed offline manifest step", async () => {
+        steps.manifest = {
+            output: "TypeError: Cannot read properties of undefined\n    at generate (/app/gen.js:4:2)\n",
+            code: 2,
+        }
+
+        expect(await runBuild()).toBe(2)
+        const text = plain(stderr)
+        expect(text).toMatch(/offline manifest failed/)
+        expect(text).toMatch(/TypeError: Cannot read properties of undefined/)
+        expect(text).not.toMatch(/Full output:/)
+    })
+
+    it("shows the manifest step's full output under --verbose", async () => {
+        steps.manifest = {
+            output: "TypeError: Cannot read properties of undefined\n    at generate (/app/gen.js:4:2)\n",
+            code: 1,
+        }
+
+        expect(await runBuild(["--verbose"])).toBe(1)
+        const text = plain(stderr)
+        expect(text).toMatch(/Full output:/)
+        expect(text).toMatch(/at generate \(\/app\/gen\.js:4:2\)/)
+    })
+})
+
+describe("catalyst build failure reporting", () => {
+    it("reports one cause once when it broke both bundles", async () => {
+        const error = "src/js/App.js:3:10: ERROR: Expected ';' but found 'x'\n"
+        steps.server = { output: error, code: 1 }
+        steps.client = { output: error, code: 1 }
+
+        expect(await runBuild()).toBe(1)
+        const text = plain(stderr)
+        expect(text.match(/Expected ';' but found 'x'/g)).toHaveLength(1)
+        expect(text).toMatch(/server \+ client bundle/)
+        expect(plain(stdout)).toMatch(/✗ Build failed/)
+    })
+
+    it("adds the registry code and the bundlers' full output under --verbose", async () => {
+        steps.client = { output: "something the patterns do not know\n", code: 4 }
+
+        expect(await runBuild(["--verbose"])).toBe(4)
+        const text = plain(stderr)
+        expect(text).toMatch(/The client bundle failed/)
+        expect(text).toMatch(/Full output:/)
+        expect(text).toMatch(/\[client\]/)
+    })
+
+    it("includes the environment under --debug", async () => {
+        steps.server = { output: "unknown failure\n", code: 1 }
+
+        expect(await runBuild(["--debug"])).toBe(1)
+        expect(plain(stderr)).toContain(process.version)
+    })
+
+    it("exits 1 rather than crashing when a bundler cannot be spawned", async () => {
+        steps.server = {
+            output: "",
+            code: 0,
+            spawnError: Object.assign(new Error("spawn node ENOENT"), { code: "ENOENT" }),
+        }
+
+        expect(await runBuild()).toBe(1)
+        // A spawn error carries no bundle label, so the report stays generic.
+        expect(plain(stderr)).toMatch(/The production bundle failed/)
+    })
+})
+
+describe("catalyst build success output", () => {
+    async function runSuccessfulBuild(argv: string[] = []) {
+        void runBuild(argv)
+        await vi.waitFor(() => expect(plain(stdout)).toMatch(/Built in/))
+        return plain(stdout)
+    }
+
+    it("cleans the previous output, surfaces bundle warnings, and lists the assets", async () => {
+        const buildDir = path.join(appDir, "build")
+        mkdirSync(buildDir)
+        writeFileSync(path.join(buildDir, "stale.js"), "old")
+
+        steps.client = {
+            output: [
+                "vite v5 building for production...",
+                "(!) Some chunks are larger than 500 kB after minification.",
+                "(!) Some chunks are larger than 500 kB after minification.",
+                "✓ built in 1.2s",
+            ].join("\n"),
+            code: 0,
+        }
+        steps.server = { output: "[plugin vite:reporter] dynamic import will not move module\n", code: 0 }
+        // The manifest step runs after the bundles, so it stands in for
+        // what they wrote.
+        steps.manifest = {
+            output: "",
+            code: 0,
+            run: () => {
+                mkdirSync(path.join(buildDir, "public", "client"), { recursive: true })
+                mkdirSync(path.join(buildDir, "server"), { recursive: true })
+                for (let i = 0; i < 13; i++) {
+                    writeFileSync(
+                        path.join(buildDir, "public", "client", `chunk-${i}.js`),
+                        "x".repeat(100 * (i + 1))
+                    )
+                }
+                writeFileSync(path.join(buildDir, "public", "client", "main.css"), "body{}".repeat(500))
+                writeFileSync(path.join(buildDir, "public", "client", "readme.txt"), "not an asset")
+                writeFileSync(path.join(buildDir, "server", "index.js"), "export default 1")
+            },
+        }
+
+        const text = await runSuccessfulBuild()
+        expect(text).toMatch(/Cleaned previous output/)
+        expect(existsSync(path.join(buildDir, "stale.js"))).toBe(false)
+        expect(text.match(/client Some chunks are larger than 500 kB/g)).toHaveLength(1)
+        expect(text).toMatch(/server \[plugin vite:reporter\] dynamic import will not move module/)
+        expect(plain(stderr)).toBe("")
+
+        expect(text).toMatch(/Client {2}build\//)
+        // Largest first, capped at twelve rows.
+        expect(text).toMatch(/├ public\/client\/main\.css\s+2\.9 kB\s+\d+ B gzip/)
+        expect(text).toMatch(/and 2 more/)
+        expect(text).not.toMatch(/readme\.txt/)
+        expect(text).toMatch(/Server {2}build\/server\/ {2}1 file, 16 B/)
+        expect(text).toMatch(/Run catalyst serve to start the production server/)
+    })
+
+    it("closes the table on its last row and skips it when nothing was produced", async () => {
+        steps.manifest = {
+            output: "",
+            code: 0,
+            run: () => {
+                mkdirSync(path.join(appDir, "build", "server"), { recursive: true })
+                writeFileSync(path.join(appDir, "build", "app.js"), "console.log(1)")
+                writeFileSync(path.join(appDir, "build", "server", "a.js"), "1")
+                writeFileSync(path.join(appDir, "build", "server", "b.js"), "2")
+            },
+        }
+        const text = await runSuccessfulBuild()
+        expect(text).toMatch(/└ app\.js/)
+        expect(text).toMatch(/2 files, 2 B/)
+        expect(text).not.toMatch(/Cleaned previous output/)
+    })
+
+    it("prints no asset table when the build wrote nothing", async () => {
+        const text = await runSuccessfulBuild()
+        expect(text).not.toMatch(/Client {2}/)
+        expect(text).toMatch(/Built client and server bundles/)
+        expect(text).toMatch(/Generated offline manifest/)
+    })
+})

package/test/scripts/preflight.test.ts

@@ -1,8 +1,8 @@
-import { describe, it, expect, beforeEach, afterEach } from "vitest"
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest"
 import { mkdtempSync, rmSync, mkdirSync, writeFileSync } from "fs"
 import { tmpdir } from "os"
 import path from "path"
-import { runStaticPreflight } from "../../src/scripts/preflight.js"
+import { runStaticPreflight, writeBuildInfo, checkBuildMatchesConfig } from "../../src/scripts/preflight.js"
 import { ERROR_CODES } from "../../src/errors/registry.js"
 
 // runStaticPreflight(appDir) reads config/config.json + package.json from a
@@ -116,3 +116,101 @@ describe("runStaticPreflight", () => {
         }
     })
 })
+
+describe("checkBuildMatchesConfig", () => {
+    const CONFIG = {
+        ...VALID_CONFIG,
+        API_URL: "https://api.example.com",
+        CLIENT_ENV_VARIABLES: ["API_URL"],
+    }
+    const SKIPPED = expect.stringContaining("Skipping the build/config check")
+
+    function buildWith(config: Record<string, unknown>, args = {}) {
+        mkdirSync(path.join(appDir, "build"), { recursive: true })
+        writeBuildInfo(appDir, config, args)
+    }
+
+    beforeEach(() => {
+        vi.spyOn(console, "warn").mockImplementation(() => {})
+    })
+    afterEach(() => {
+        vi.restoreAllMocks()
+    })
+
+    it("returns null when config.json is unchanged since the build", () => {
+        writeApp({ config: CONFIG })
+        buildWith(CONFIG)
+        expect(checkBuildMatchesConfig(appDir)).toBeNull()
+        expect(console.warn).not.toHaveBeenCalledWith(SKIPPED)
+    })
+
+    it("ignores config keys that are not inlined into the build", () => {
+        writeApp({ config: { ...CONFIG, NODE_SERVER_PORT: 4000 } })
+        buildWith(CONFIG)
+        expect(checkBuildMatchesConfig(appDir)).toBeNull()
+    })
+
+    it("PREFLIGHT-022 when PUBLIC_STATIC_ASSET_URL changed", () => {
+        writeApp({ config: { ...CONFIG, PUBLIC_STATIC_ASSET_URL: "http://192.168.1.5:3000" } })
+        buildWith(CONFIG)
+        const err = checkBuildMatchesConfig(appDir)
+        expect(err?.code).toBe(ERROR_CODES.PREFLIGHT_BUILD_STALE)
+        expect(err?.details).toContain(
+            'PUBLIC_STATIC_ASSET_URL: built with "http://localhost:3000", now "http://192.168.1.5:3000"'
+        )
+    })
+
+    it("PREFLIGHT-022 when a CLIENT_ENV_VARIABLES value changed", () => {
+        writeApp({ config: { ...CONFIG, API_URL: "https://staging.example.com" } })
+        buildWith(CONFIG)
+        expect(checkBuildMatchesConfig(appDir)?.details).toContain(
+            'API_URL: built with "https://api.example.com", now "https://staging.example.com"'
+        )
+    })
+
+    it("PREFLIGHT-022 when a variable is added to CLIENT_ENV_VARIABLES", () => {
+        writeApp({ config: { ...CONFIG, CUSTOM_VAR: "x", CLIENT_ENV_VARIABLES: ["API_URL", "CUSTOM_VAR"] } })
+        buildWith(CONFIG)
+        expect(checkBuildMatchesConfig(appDir)?.details).toContain('CUSTOM_VAR: built with unset, now "x"')
+    })
+
+    it("compares against KEY=value CLI arguments, which win over config.json", () => {
+        const args = { PUBLIC_STATIC_ASSET_URL: "http://cdn.example.com" }
+        writeApp({ config: CONFIG })
+        buildWith(CONFIG, args)
+        expect(checkBuildMatchesConfig(appDir, args)).toBeNull()
+        expect(checkBuildMatchesConfig(appDir)?.code).toBe(ERROR_CODES.PREFLIGHT_BUILD_STALE)
+    })
+
+    it("treats a CLI argument equal to the config.json object as unchanged", () => {
+        const config = { ...CONFIG, OPTIONS: { enabled: true }, CLIENT_ENV_VARIABLES: ["OPTIONS"] }
+        writeApp({ config })
+        buildWith(config)
+        expect(checkBuildMatchesConfig(appDir, { OPTIONS: '{"enabled":true}' })).toBeNull()
+        expect(checkBuildMatchesConfig(appDir, { CLIENT_ENV_VARIABLES: '["OPTIONS"]' })).toBeNull()
+    })
+
+    it("warns and passes when the build has no build info file", () => {
+        writeApp({ config: CONFIG })
+        expect(checkBuildMatchesConfig(appDir)).toBeNull()
+        expect(console.warn).toHaveBeenCalledWith(SKIPPED)
+    })
+
+    it.each([["{ not json"], ["null"], ["[]"]])(
+        "warns and passes when the build info file is %s",
+        (contents) => {
+            writeApp({ config: CONFIG })
+            mkdirSync(path.join(appDir, "build"), { recursive: true })
+            writeFileSync(path.join(appDir, "build", ".catalyst-build.json"), contents)
+            expect(checkBuildMatchesConfig(appDir)).toBeNull()
+            expect(console.warn).toHaveBeenCalledWith(SKIPPED)
+        }
+    )
+
+    it("warns and passes when CLIENT_ENV_VARIABLES cannot be parsed", () => {
+        writeApp({ config: CONFIG })
+        buildWith(CONFIG)
+        expect(checkBuildMatchesConfig(appDir, { CLIENT_ENV_VARIABLES: "not-json" })).toBeNull()
+        expect(console.warn).toHaveBeenCalledWith(SKIPPED)
+    })
+})

package/test/scripts/serve.test.ts

@@ -0,0 +1,102 @@
+import { EventEmitter } from "node:events"
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs"
+import { tmpdir } from "node:os"
+import path from "node:path"
+import { afterEach, beforeEach, expect, it, vi } from "vitest"
+
+// serve.js runs on import; the preflight is stubbed and spawn is recorded so
+// the test can check how the production server is started.
+const preflight = vi.hoisted(() => ({ staleBuild: null as null | { code: string } }))
+vi.mock("../../src/scripts/preflight.js", () => ({
+    runStaticPreflightOrExit: () => {},
+    checkBuildMatchesConfig: () => preflight.staleBuild,
+    renderRegistryError: (error: { code: string }) => `rendered ${error.code}\n`,
+}))
+
+const spawned: { args: string[]; options: { stdio: unknown; env: Record<string, string> } }[] = []
+vi.mock("child_process", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("child_process")>()
+    const spawn = (_cmd: string, args: string[], options: (typeof spawned)[number]["options"]) => {
+        spawned.push({ args, options })
+        return Object.assign(new EventEmitter(), { stdout: null, stderr: null, kill: () => true })
+    }
+    return { ...actual, default: { ...actual, spawn }, spawn }
+})
+
+let appDir: string
+let stderr: string
+let exit: ReturnType<typeof vi.spyOn>
+const originalPwd = process.env.PWD
+
+// serve.js runs on import, so each test loads a fresh copy.
+async function serve() {
+    vi.resetModules()
+    await import("../../src/scripts/serve.js")
+}
+
+beforeEach(() => {
+    appDir = mkdtempSync(path.join(tmpdir(), "catalyst-serve-"))
+    mkdirSync(path.join(appDir, "config"))
+    mkdirSync(path.join(appDir, "build"))
+    writeFileSync(path.join(appDir, "config", "config.json"), JSON.stringify({ BUILD_OUTPUT_PATH: "build" }))
+    writeFileSync(path.join(appDir, "package.json"), JSON.stringify({ name: "fixture-app" }))
+    process.env.PWD = appDir
+    spawned.length = 0
+    preflight.staleBuild = null
+    stderr = ""
+    // Not thrown: startProd is not awaited, so a throw would surface as an
+    // unhandled rejection rather than stop it.
+    exit = vi.spyOn(process, "exit").mockImplementation((() => undefined) as never)
+    vi.spyOn(process.stderr, "write").mockImplementation(((chunk: string) => {
+        stderr += String(chunk)
+        return true
+    }) as never)
+})
+
+afterEach(() => {
+    vi.restoreAllMocks()
+    process.env.PWD = originalPwd
+    for (const signal of ["SIGTERM", "SIGHUP"] as const) process.removeAllListeners(signal)
+    rmSync(appDir, { recursive: true, force: true })
+})
+
+it("hands the production server the terminal's own stdout and stderr", async () => {
+    await serve()
+    await vi.waitFor(() => expect(spawned).toHaveLength(1))
+
+    const { options } = spawned[0]
+    // Inherited, so log shippers read the app's lines exactly as written --
+    // and unwrapped, so the server prints no banner fences.
+    expect(options.stdio).toBe("inherit")
+    expect(options.env.CATALYST_WRAPPED).toBeUndefined()
+    expect(options.env.NODE_ENV).toBe("production")
+})
+
+it("says to build first when there is no production build", async () => {
+    rmSync(path.join(appDir, "build"), { recursive: true })
+    await serve()
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1))
+
+    expect(stderr).toMatch(/No production build in build\//)
+    expect(stderr).toMatch(/Run catalyst build first, then catalyst serve\./)
+})
+
+it("refuses a build that no longer matches the config", async () => {
+    preflight.staleBuild = { code: "BUILD_CONFIG_MISMATCH" }
+    await serve()
+    await vi.waitFor(() => expect(exit).toHaveBeenCalledWith(1))
+
+    expect(stderr).toBe("rendered BUILD_CONFIG_MISMATCH\n")
+})
+
+it("passes --inspect through to the server", async () => {
+    const argv = process.argv
+    process.argv = [argv[0], "serve.js", "--inspect"]
+    try {
+        await serve()
+        await vi.waitFor(() => expect(spawned).toHaveLength(1))
+    } finally {
+        process.argv = argv
+    }
+    expect(spawned[0].args[0]).toBe("--inspect")
+})

package/test/server/fixtures/template/src/js/routes/index.jsx

@@ -62,8 +62,16 @@ const FetcherErrorLoadable = loadable({
     }),
 })
 
+// A component that throws while rendering -- the most common dev-time
+// failure. The handler must report it once and answer with a 500, not
+// re-render it from every fallback and leave the request open.
+function RenderErrorPage() {
+    throw new Error("render exploded")
+}
+
 const routes = [
     { path: "/", component: HomePage },
+    { path: "/render-error", component: RenderErrorPage },
     { path: "/widget", component: WidgetPage },
     { path: "/fetcher-error", component: FetcherErrorLoadable },
     { path: "*", component: NotFoundPage },

package/test/server/handler.test.ts

@@ -160,6 +160,23 @@ describe("SSR handler", () => {
         expect(res.getHtml()).toContain("<html")
     })
 
+    it("reports a component render error once and answers 500 instead of hanging", async () => {
+        const { default: handler } = await import("../../src/server/renderer/handler.jsx")
+        const { req, res } = makeReqRes("/render-error")
+
+        await handler(req, res)
+        await res.waitForEnd()
+
+        // One report: the render failure used to be logged again by the
+        // fetcher, serverSideFunction and request catch sites, each of which
+        // re-rendered the same throwing tree.
+        const logged = (console.error as any).mock.calls.flat().join("\n")
+        expect(logged.match(/\[RUNTIME-WEB-\d+\]/g)).toEqual(["[RUNTIME-WEB-001]"])
+        // And the request is finished rather than left open.
+        expect(res.statusCode).toBe(500)
+        expect(res.isEnded()).toBe(true)
+    })
+
     it("fails the request with 500 (no render) when configureStore is not a function", async () => {
         // handler.jsx imports createStore as a module-scope default binding,
         // so swap the fixture module before the fresh import. A non-function