catalyst-core 1.0.2-canary.1 → 1.0.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/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

package/test/server/logger.test.ts

@@ -0,0 +1,185 @@
+import { Writable } from "node:stream"
+import winston from "winston"
+import { afterEach, beforeEach, expect, it, vi } from "vitest"
+
+// The rotating file transport, replaced by one that records its options and
+// what it was given, so enabling file logging touches no disk.
+const rotated = vi.hoisted(() => ({
+    options: [] as Record<string, unknown>[],
+    records: [] as Record<string, unknown>[],
+}))
+vi.mock("winston-daily-rotate-file", async () => {
+    const { default: winston } = await import("winston")
+    // winston re-exports winston-transport at runtime; its typings do not.
+    const { Transport } = winston as unknown as {
+        Transport: new (options?: object) => object
+    }
+    class FakeRotate extends Transport {
+        constructor(options: Record<string, unknown>) {
+            super(options)
+            rotated.options.push(options)
+        }
+        log(info: Record<string, unknown>, done: () => void) {
+            rotated.records.push(info)
+            done()
+        }
+    }
+    return { default: FakeRotate }
+})
+
+// What the file logs receive: every winston logger the app logger creates
+// gets an extra in-memory transport, so the test reads the same serialized
+// JSON lines a DailyRotateFile would write.
+let written: Record<string, unknown>[]
+let loggers: winston.Logger[]
+let consoleLines: string[]
+
+beforeEach(() => {
+    written = []
+    loggers = []
+    consoleLines = []
+    rotated.options.length = 0
+    rotated.records.length = 0
+    const createLogger = winston.createLogger
+    vi.spyOn(winston, "createLogger").mockImplementation((options) => {
+        const logger = createLogger(options)
+        const stream = new Writable({
+            write(chunk, _encoding, done) {
+                written.push(JSON.parse(String(chunk)))
+                done()
+            },
+        })
+        logger.add(new winston.transports.Stream({ stream }))
+        loggers.push(logger)
+        return logger
+    })
+    vi.spyOn(console, "log").mockImplementation((line: string) => {
+        consoleLines.push(String(line).replace(/\u001b\[[0-9;]*m/g, ""))
+    })
+})
+
+afterEach(() => {
+    vi.restoreAllMocks()
+})
+
+type AppLogger = Record<"info" | "error" | "debug", (msg: unknown) => void>
+
+async function appLogger(config: Record<string, unknown> = {}): Promise<AppLogger> {
+    vi.resetModules()
+    const { configureLogger } = await import("../../src/logger.js")
+    return configureLogger({ enableFileLogging: false, enableConsoleLogging: false, ...config } as never)
+}
+
+it("keeps a plain object's fields queryable in the file log", async () => {
+    const logger = await appLogger()
+    const payload = { message: "upstream failed", url: "/api/orders" }
+    logger.error(payload)
+
+    await vi.waitFor(() => expect(written).toHaveLength(1))
+    expect(written[0]).toMatchObject({ message: "upstream failed", url: "/api/orders", level: "error" })
+    // The caller's object is not written on.
+    expect(payload).toEqual({ message: "upstream failed", url: "/api/orders" })
+})
+
+it("logs a circular object, and an Error inside it as its stack", async () => {
+    const logger = await appLogger()
+    const payload: Record<string, unknown> = { message: "bad", cause: new Error("root cause") }
+    payload.self = payload
+    logger.info(payload)
+
+    await vi.waitFor(() => expect(written).toHaveLength(1))
+    expect(written[0]).toMatchObject({ message: "bad", self: "[Circular]", level: "info" })
+    expect(written[0].cause).toMatch(/^Error: root cause\n\s+at /)
+})
+
+it("logs strings and Errors as text", async () => {
+    const logger = await appLogger()
+    logger.info("plain words")
+    logger.error(new Error("boom"))
+
+    await vi.waitFor(() => expect(written).toHaveLength(2))
+    expect(written[0].message).toBe("plain words")
+    expect(written[1].message).toMatch(/^Error: boom\n\s+at /)
+})
+
+it("echoes each level to the terminal with its label", async () => {
+    const logger = await appLogger()
+    logger.info("ready")
+    logger.error("failed")
+    logger.debug("details")
+    expect(consoleLines).toEqual(["INFO: ready", "ERROR: failed", "DEBUG: details"])
+
+    await vi.waitFor(() => expect(written).toHaveLength(2))
+    expect(written.map((record) => record.level)).toEqual(["info", "error"])
+})
+
+it("makes debug a no-op when debug logs are off", async () => {
+    for (const enableDebugLogs of [false, "false"]) {
+        consoleLines.length = 0
+        const logger = await appLogger({ enableDebugLogs })
+        logger.debug("hidden")
+        expect(consoleLines).toEqual([])
+    }
+})
+
+it("adds the console transport and a rotating file per level when enabled", async () => {
+    const srcPath = process.env.src_path
+    process.env.src_path = "/app"
+    // The console transport is real but kept quiet.
+    const consoleLog = vi
+        .spyOn(winston.transports.Console.prototype, "log")
+        .mockImplementation(((_info: unknown, done: () => void) => done()) as never)
+    try {
+        const logger = await appLogger({ enableFileLogging: "true", enableConsoleLogging: true })
+        logger.info({ message: "booted", port: 3005 })
+
+        expect(rotated.options.map((options) => options.filename)).toEqual([
+            "/app/logs/info/%DATE%.info.log",
+            "/app/logs/debug/%DATE%.debug.log",
+            "/app/logs/error/%DATE%.error.log",
+        ])
+        expect(rotated.options.map((options) => options.level)).toEqual(["info", "debug", "error"])
+        for (const created of loggers) {
+            expect(
+                created.transports.some((transport) => transport instanceof winston.transports.Console)
+            ).toBe(true)
+        }
+        await vi.waitFor(() => expect(rotated.records).toHaveLength(1))
+        expect(rotated.records[0]).toMatchObject({ message: "booted", port: 3005, level: "info" })
+        expect(consoleLog).toHaveBeenCalled()
+    } finally {
+        if (srcPath === undefined) delete process.env.src_path
+        else process.env.src_path = srcPath
+    }
+})
+
+it("renders values JSON cannot, instead of dropping or throwing on them", async () => {
+    const logger = await appLogger()
+    const bare = new Error("no stack")
+    bare.stack = ""
+    logger.info({ count: BigInt("9007199254740993") })
+    logger.info(bare)
+    logger.info(function namedHandler() {})
+    logger.info({
+        toJSON() {
+            throw new Error("cannot serialise")
+        },
+    })
+    logger.info([1, "two"])
+    logger.info(42)
+
+    expect(consoleLines).toEqual([
+        'INFO: {"count":"9007199254740993"}',
+        "INFO: Error: no stack",
+        expect.stringMatching(/^INFO: function namedHandler\(\) \{\s*\}$/),
+        "INFO: [object Object]",
+        'INFO: [1,"two"]',
+        "INFO: 42",
+    ])
+    await vi.waitFor(() => expect(written).toHaveLength(6))
+    // Only a plain object becomes a structured record; the rest stay text.
+    expect(JSON.stringify(written[0])).toContain('"count":"9007199254740993"')
+    expect(written[3].message).toBe("[object Object]")
+    expect(written[4].message).toBe('[1,"two"]')
+    expect(written[5].message).toBe("42")
+})