@akanjs/devkit 3.0.0-beta.25 → 3.0.0-beta.27

package/csrE2e/csrRootLayout.e2e.test.ts

@@ -0,0 +1,134 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { CsrE2eHarness } from "./csrE2eHarness.fixture";
+
+//* Where a CSR page lands, not only what its console says. CSR's root layout renders the pages in a frame of its own
+//* and hides what it wraps, so a layout the route table puts at the root wraps no page: an app with its root layout
+//* in a route group once rendered nothing, then rendered its dashboard outside the lock screen that wraps it.
+const EXPLORE = "/explore";
+const TAB_A = "/e2e/stack/tab-a";
+//? The web layout draws no bottom chrome, so the `(tab)` layout shows in the route table, not in the text.
+const exploreText = ["Where are you headed today?", "Popular stays right now"];
+
+interface RouteTableWindow {
+  __akan?: { inspect(): { executed: string[] }; require(id: string): unknown };
+}
+
+//? A page's element is inside its layout's marker, outside the hidden provider container, and on screen.
+const placement = async (harness: CsrE2eHarness, page: string) =>
+  await harness.evaluate((selector: string) => {
+    const element = document.querySelector(selector);
+    return {
+      rendered: element !== null,
+      inLayout: element?.closest('[data-e2e="public-layout"]') != null,
+      hidden: element?.closest("#csr-provider-children") != null,
+      visible: element?.checkVisibility() ?? false,
+    };
+  }, `[data-e2e="${page}"]`);
+
+describe.skipIf(!CsrE2eHarness.enabled)("CSR layouts under a root layout (minimal, (tab))", () => {
+  let csr: CsrE2eHarness;
+
+  beforeAll(async () => {
+    csr = await CsrE2eHarness.start({
+      app: "minimal",
+      port: Number(process.env.AKAN_CSR_E2E_ROOT_LAYOUT_PORT ?? 8497),
+    });
+  }, 240_000);
+
+  afterAll(async () => {
+    // biome-ignore lint/suspicious/noUnnecessaryConditions: unassigned when beforeAll threw before the harness started
+    await csr?.close();
+  }, 60_000);
+
+  const rendered = async (texts: string[]) =>
+    await csr.waitFor(
+      (want: string[]) => want.every((text) => (document.getElementById("root")?.innerText ?? "").includes(text)),
+      { args: [texts], timeout: 30_000 },
+    );
+  //? The table the running bundle built, read through the dev registry: what the router renders from.
+  const layerCounts = async () =>
+    await csr.evaluate(() => {
+      const akan = (window as unknown as RouteTableWindow).__akan;
+      const id = akan?.inspect().executed.find((executed) => executed.endsWith("webkit/CsrRouteTable.ts"));
+      const table = id
+        ? (akan?.require(id) as {
+            CsrRouteTable: {
+              active: {
+                snapshot(): { pathRoutes: { path: string; renderRootLayouts: unknown[]; renderLayouts: unknown[] }[] };
+              };
+            };
+          })
+        : null;
+      return Object.fromEntries(
+        (table?.CsrRouteTable.active.snapshot().pathRoutes ?? []).map((route) => [
+          route.path,
+          { root: route.renderRootLayouts.length, layouts: route.renderLayouts.length },
+        ]),
+      );
+    });
+
+  test("a nested root boundary renders with its pages, not at the root", async () => {
+    await csr.open(EXPLORE);
+    await rendered(exploreText);
+    const counts = await layerCounts();
+    expect(counts["/:lang/explore"]?.root).toBe(counts["/:lang/e2e/stack/tab-a"]?.root);
+    expect(counts["/:lang/explore"]?.layouts).toBe(1);
+    expect(csr.consoleMessages().filter((message) => /no root layout|error occurred/.test(message))).toEqual([]);
+  }, 60_000);
+
+  test("leaving the group and coming back renders each side", async () => {
+    await csr.open(EXPLORE);
+    await rendered(exploreText);
+    await csr.navigate(TAB_A);
+    await csr.waitFor(() => document.querySelector('[data-e2e-probe="tab-a"]') !== null, { timeout: 30_000 });
+    await csr.back();
+    await rendered(exploreText);
+  }, 90_000);
+});
+
+describe.skipIf(!CsrE2eHarness.enabled)("a root layout in a route group (groupedroot, page/(app)/_layout)", () => {
+  let harness: CsrE2eHarness;
+
+  beforeAll(async () => {
+    harness = await CsrE2eHarness.start({
+      app: "groupedroot",
+      port: Number(process.env.AKAN_CSR_E2E_GROUPED_ROOT_PORT ?? 8498),
+    });
+  }, 240_000);
+
+  afterAll(async () => {
+    // biome-ignore lint/suspicious/noUnnecessaryConditions: unassigned when beforeAll threw before the harness started
+    await harness?.close();
+  }, 60_000);
+
+  const open = async (path: string, page: string, csr: boolean) => {
+    await harness.open(path, { csr });
+    await harness.waitFor((selector: string) => document.querySelector(selector) !== null, {
+      args: [`[data-e2e="${page}"]`],
+      timeout: 30_000,
+    });
+  };
+
+  test.each([
+    ["SSR", false],
+    ["CSR", true],
+  ] as const)(
+    "%s: a page renders inside the (public) layout that wraps it",
+    async (_mode, csr) => {
+      for (const [path, page] of [
+        ["/dashboard", "dashboard"],
+        ["/", "index"],
+      ] as const) {
+        await open(path, page, csr);
+        expect(await placement(harness, page)).toEqual({
+          rendered: true,
+          inLayout: true,
+          hidden: false,
+          visible: true,
+        });
+      }
+      expect(harness.consoleMessages().filter((message) => /no root layout|error occurred/.test(message))).toEqual([]);
+    },
+    90_000,
+  );
+});

package/csrE2e/registryVendor.e2e.test.ts

@@ -0,0 +1,221 @@
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { rm } from "node:fs/promises";
+import path from "node:path";
+import { CsrE2eHarness } from "./csrE2eHarness.fixture";
+
+//* Package shapes that once turned a whole dev vendor file into a SyntaxError or a startup throw, each followed by
+//* nothing but distant MissingModuleErrors. Written in for the run only: no app of the repo depends on them.
+const workspaceRoot = path.resolve(import.meta.dir, "../../../..");
+const vendorRoot = path.join(workspaceRoot, "node_modules/@akan-e2e");
+const probeFile = path.join(workspaceRoot, "apps/minimal/ui/RegistryVendor.tsx");
+const pageFile = path.join(workspaceRoot, "apps/minimal/page/(home)/e2e/vendor.tsx");
+const cliFile = path.join(workspaceRoot, "dist/pkgs/@akanjs/cli/index.js");
+const VENDOR = "/e2e/vendor";
+const expected = { prebundled: 3, metaDev: true, metaUrl: "http:", used: "used", inspectish: "yes" };
+const broken =
+  /SyntaxError|MissingModuleError|no module registered|Node built-in|left out of the dev registry|error occurred in one of your React components/;
+
+const packages: Record<string, string> = {
+  //? esbuild's own interop helpers, as the @mermaid-js/parser chunks ship them.
+  "prebundled/package.json": JSON.stringify({ name: "@akan-e2e/prebundled", type: "module", main: "chunk.mjs" }),
+  "prebundled/chunk.mjs": `var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __reExport = (target, mod, secondTarget) => (__copyProps(target, mod, "default"), secondTarget && __copyProps(secondTarget, mod, "default"));
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target, mod));
+var parts = {};
+__reExport(parts, { a: 1 });
+var wrapped = __toESM({ b: 2 });
+export const prebundled = parts.a + wrapped.b;
+`,
+  //? jotai's and zustand's ESM development check.
+  "meta-env/package.json": JSON.stringify({
+    name: "@akan-e2e/meta-env",
+    type: "module",
+    exports: { ".": "./esm/index.mjs" },
+  }),
+  "meta-env/esm/index.mjs": `export const metaDev = (import.meta.env ? import.meta.env.MODE : void 0) !== "production";
+export const metaUrl = new URL(import.meta.url).protocol;
+`,
+  //? vfile behind unified: a side-effect-free barrel whose unused re-exports reach Node-only files through `#imports`.
+  "barrel/package.json": JSON.stringify({
+    name: "@akan-e2e/barrel",
+    type: "module",
+    main: "index.js",
+    sideEffects: false,
+    imports: {
+      "#where": { node: "./where.node.js", default: "./where.browser.js" },
+      "#other": { node: "./other.node.js", default: "./other.browser.js" },
+    },
+  }),
+  "barrel/index.js": `export { used } from "./used.js";
+export { unused } from "./unused.js";
+export { other } from "#other";
+`,
+  "barrel/used.js": `export const used = "used";\n`,
+  "barrel/unused.js": `import { where } from "#where";\nexport const unused = where;\n`,
+  "barrel/where.node.js": `import path from "node:path";\nexport const where = path.sep;\n`,
+  "barrel/where.browser.js": `export const where = "browser";\n`,
+  "barrel/other.node.js": `import path from "node:path";\nexport const other = path.sep;\n`,
+  "barrel/other.browser.js": `export const other = "browser";\n`,
+  //? object-inspect: a `browser` map that turns a Node-only file off.
+  "inspectish/package.json": JSON.stringify({
+    name: "@akan-e2e/inspectish",
+    main: "index.js",
+    browser: { "./util.inspect.js": false },
+  }),
+  //? Bun's own bundle gives the require `() => ({})` where the registry gives `{}`; either way it must not throw.
+  "inspectish/index.js": `var inspect = require("./util.inspect");\nmodule.exports = { loaded: inspect ? "yes" : "no" };\n`,
+  "inspectish/util.inspect.js": `module.exports = require("util").inspect;\n`,
+};
+
+const probeSource = `"use client";
+import { used } from "@akan-e2e/barrel";
+import inspectish from "@akan-e2e/inspectish";
+import { metaDev, metaUrl } from "@akan-e2e/meta-env";
+import { prebundled } from "@akan-e2e/prebundled";
+import { useEffect, useState } from "react";
+
+export const RegistryVendor = () => {
+  const [hydrated, setHydrated] = useState(false);
+  useEffect(() => setHydrated(true), []);
+  return (
+    <div data-e2e="vendor" data-e2e-hydrated={hydrated ? "1" : "0"} data-e2e-hot="0">
+      {JSON.stringify({ prebundled, metaDev, metaUrl, used, inspectish: inspectish.loaded })}
+    </div>
+  );
+};
+`;
+
+const pageSource = `import { page } from "akanjs/client";
+import { RegistryVendor } from "../../../ui/RegistryVendor";
+
+export default page()
+  .config({ transition: "none", gesture: false })
+  .render(() => (
+    <main>
+      <RegistryVendor />
+    </main>
+  ));
+`;
+
+interface VendorWindow {
+  __akan?: { has(id: string): boolean; inspect(): { started: boolean; failed: boolean; executed: string[] } };
+}
+
+describe.skipIf(!CsrE2eHarness.enabled)("dev registries with the package shapes that broke them (minimal)", () => {
+  //? Run first too, and safe to run twice: a run killed mid-way (a timeout, SIGKILL, a Jenkins abort on a reused
+  //? workspace) leaves the packages, the probe and the page behind, and `akan sync` rebuilds the barrel it joined.
+  const cleanup = async () => {
+    await Promise.all([
+      rm(vendorRoot, { recursive: true, force: true }),
+      rm(probeFile, { force: true }),
+      rm(pageFile, { force: true }),
+    ]);
+    for (const command of [
+      ["bun", path.join(workspaceRoot, "pkgs/@akanjs/cli/build.ts")],
+      ["bun", cliFile, "sync", "minimal"],
+    ]) {
+      const done = Bun.spawnSync(command, { cwd: workspaceRoot, stdout: "ignore" });
+      if (done.exitCode !== 0)
+        throw new Error(`[csr-e2e] ${command.slice(1).join(" ")} failed: ${done.stderr.toString()}`);
+    }
+  };
+
+  beforeAll(async () => {
+    await cleanup();
+    for (const [file, text] of Object.entries(packages)) await Bun.write(path.join(vendorRoot, file), text);
+    await Bun.write(probeFile, probeSource);
+    await Bun.write(pageFile, pageSource);
+  }, 120_000);
+
+  afterAll(cleanup, 120_000);
+
+  describe.each([
+    ["registry", 8495],
+    ["artifact", 8496],
+  ] as const)("AKAN_DEV_CSR=%s", (mode, port) => {
+    let harness: CsrE2eHarness;
+
+    beforeAll(async () => {
+      harness = await CsrE2eHarness.start({ app: "minimal", port, env: { AKAN_DEV_CSR: mode } });
+    }, 240_000);
+
+    afterAll(async () => {
+      // biome-ignore lint/suspicious/noUnnecessaryConditions: unassigned when beforeAll threw before the harness started
+      await harness?.close();
+    }, 60_000);
+
+    const probeValues = async () =>
+      JSON.parse((await harness.text('[data-e2e="vendor"]', { mounted: true }))[0] ?? "null") as typeof expected | null;
+    const openVendor = async (csr: boolean) => {
+      await harness.open(VENDOR, { csr });
+      await harness.waitFor(
+        () => document.querySelector('[data-e2e="vendor"]')?.getAttribute("data-e2e-hydrated") === "1",
+        { timeout: 60_000 },
+      );
+    };
+    const registryState = async () =>
+      await harness.evaluate(() => {
+        const akan = (window as unknown as VendorWindow).__akan;
+        if (!akan) return null;
+        const { started, failed, executed } = akan.inspect();
+        return {
+          started,
+          failed,
+          refresh: executed.some((id) => id.includes("react-refresh/")),
+          vendors: [
+            "node_modules/@akan-e2e/prebundled/chunk.mjs",
+            "node_modules/@akan-e2e/meta-env/esm/index.mjs",
+            "node_modules/@akan-e2e/barrel/unused.js",
+            "node_modules/@akan-e2e/inspectish/index.js",
+          ].filter((id) => akan.has(id)),
+        };
+      });
+
+    test("an SSR page hydrates its client code with every package shape in it", async () => {
+      await openVendor(false);
+      expect(await probeValues()).toEqual(expected);
+      expect(await registryState()).toMatchObject({ started: true, failed: false });
+      expect((await registryState())?.vendors).toHaveLength(4);
+      expect(harness.consoleMessages().filter((message) => broken.test(message))).toEqual([]);
+    }, 120_000);
+
+    test("a CSR page boots and renders with every package shape in it", async () => {
+      await openVendor(true);
+      expect(await probeValues()).toEqual(expected);
+      const state = await registryState();
+      if (mode === "registry") expect(state).toMatchObject({ started: true, failed: false, refresh: true });
+      if (mode === "registry") expect(state?.vendors).toHaveLength(4);
+      expect(harness.consoleMessages().filter((message) => broken.test(message))).toEqual([]);
+    }, 120_000);
+
+    test("a save to the page's client code shows on the CSR page", async () => {
+      await openVendor(true);
+      await harness.editSource(
+        probeFile,
+        (source) => source.replace('data-e2e-hot="0"', 'data-e2e-hot="1"'),
+        async () => {
+          await harness.waitFor(
+            () => document.querySelector('[data-e2e="vendor"]')?.getAttribute("data-e2e-hot") === "1",
+            { timeout: 60_000 },
+          );
+        },
+      );
+      //? The registry patches in place; the single-file artifact reloads on every save, which is its contract.
+      expect(await harness.reloaded()).toBe(mode === "artifact");
+      expect(await probeValues()).toEqual(expected);
+    }, 120_000);
+  });
+});

package/frontendBuild/clientEntryDiscovery.test.ts

@@ -34,4 +34,79 @@ describe("GraphClientEntryDiscovery", () => {
       expect(await discovery.discover([file("S.tsx")])).toEqual([file("C.tsx")]);
     }
   });
+
+  const tempDir = async () => {
+    const dir = await mkdtemp(path.join(os.tmpdir(), "akan-discovery-"));
+    dirs.push(dir);
+    return (name: string) => path.join(dir, name);
+  };
+
+  test("an entry moved into a folder, or to another extension, is found once the move is invalidated", async () => {
+    const file = await tempDir();
+    await Bun.write(file("S.tsx"), 'import "./ui/Chart";\nimport "./ui/Card";\n');
+    await Bun.write(file("ui/Chart.tsx"), '"use client";\nexport const Chart = () => null;\n');
+    await Bun.write(file("ui/Card.tsx"), '"use client";\nexport const Card = () => null;\n');
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+    expect(await discovery.discover([file("S.tsx")])).toEqual([file("ui/Card.tsx"), file("ui/Chart.tsx")]);
+
+    await rm(file("ui/Chart.tsx"));
+    await Bun.write(file("ui/Chart/index.tsx"), '"use client";\nexport const Chart = () => null;\n');
+    await rm(file("ui/Card.tsx"));
+    await Bun.write(file("ui/Card.ts"), '"use client";\nexport const Card = () => null;\n');
+    discovery.invalidate([file("ui/Chart.tsx"), file("ui/Chart/index.tsx"), file("ui/Card.tsx"), file("ui/Card.ts")]);
+    expect(await discovery.discover([file("S.tsx")])).toEqual([file("ui/Card.ts"), file("ui/Chart/index.tsx")]);
+  });
+
+  test("a resolution still in flight when its target appears is not what the next walk reads", async () => {
+    const file = await tempDir();
+    await Bun.write(file("S.tsx"), 'import "./B";\n');
+    await Bun.write(file("B.tsx"), 'import "@demo/C";\nexport const b = 1;\n');
+    const gate = Promise.withResolvers<void>();
+    const seen = Promise.withResolvers<void>();
+    let calls = 0;
+    const resolvePackage = async () => {
+      calls += 1;
+      const exists = await Bun.file(file("C.tsx")).exists();
+      if (calls === 1) {
+        seen.resolve();
+        await gate.promise;
+      }
+      return exists ? { entryFile: file("C.tsx") } : null;
+    };
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, resolvePackage as never);
+    const walk = discovery.discover([file("S.tsx")]);
+    await seen.promise;
+    await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+    discovery.invalidate([file("C.tsx")]);
+    gate.resolve();
+    await walk;
+    expect(await discovery.discover([file("S.tsx")])).toEqual([file("C.tsx")]);
+  });
+
+  test("a dense import cycle is walked once per file, not once per path", async () => {
+    const file = await tempDir();
+    const names = Array.from({ length: 12 }, (_, idx) => `M${idx}.tsx`);
+    for (const name of names)
+      await Bun.write(file(name), names.map((other) => `import "./${other.replace(".tsx", "")}";\n`).join(""));
+    await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+    await Bun.write(
+      file("M11.tsx"),
+      `${names.map((other) => `import "./${other.replace(".tsx", "")}";\n`).join("")}import "./C";\n`,
+    );
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+    const started = performance.now();
+    expect(await discovery.discover([file("M0.tsx")])).toEqual([file("C.tsx")]);
+    expect(performance.now() - started).toBeLessThan(2_000);
+    expect(await discovery.discover([file("M5.tsx")])).toEqual([file("C.tsx")]);
+  });
+
+  test("a file walked inside an import cycle keeps no partial result for a walk that starts at it", async () => {
+    const file = await tempDir();
+    await Bun.write(file("A.tsx"), 'import "./B";\nimport "./C";\n');
+    await Bun.write(file("B.tsx"), 'import "./A";\n');
+    await Bun.write(file("C.tsx"), '"use client";\nexport const C = () => null;\n');
+    const discovery = new GraphClientEntryDiscovery({ barrelImports: [] }, (async () => null) as never);
+    expect(await discovery.discover([file("A.tsx")])).toEqual([file("C.tsx")]);
+    expect(await discovery.discover([file("B.tsx")])).toEqual([file("C.tsx")]);
+  });
 });