@uniflowed/vite 0.0.0-alpha.6 → 0.0.0-alpha.8

package/index.js

@@ -16,6 +16,10 @@
 //                 that hydrates it, and the server entry that renders it. In
 //                 development it also renders every HTML request on the
 //                 server, so `uf dev` serves the same markup `uf build` writes.
+//                 The client's copy of the route table is not the server's:
+//                 `internal/rsc.js` reads the RSC analysis and leaves out the
+//                 page of every route no client boundary reaches, so that
+//                 route's modules never enter the browser bundle.
 // * `uf:mdx`    — `@mdx-js/rollup`, configured for React with GitHub-flavoured
 //                 markdown, front matter, heading ids and build-time syntax
 //                 highlighting, so `.mdx` works with
@@ -30,6 +34,7 @@ import path from "node:path";
 import mdx from "@mdx-js/rollup";
 import rehypeSlug from "rehype-slug";
 
+import { emit, reportRenderError } from "./internal/events.js";
 import { highlightPlugin } from "./internal/highlight.js";
 import remarkFrontmatter from "remark-frontmatter";
 import remarkGfm from "remark-gfm";
@@ -42,7 +47,9 @@ import {
   preambleCode,
   refreshRuntimeSource,
 } from "./internal/refresh.js";
+import { RSC_MANIFEST_ENV, clientRouteFilter, readRscManifest } from "./internal/rsc.js";
 import {
+  RESERVED,
   VIRTUAL,
   clientModuleSource,
   routesModuleSource,
@@ -50,6 +57,8 @@ import {
   serverModuleSource,
 } from "./internal/routes.js";
 import { TransformService, isFlowModule } from "@uniflowed/host/transform";
+import { send, toRequest } from "./internal/http.js";
+import { withRequest } from "./internal/serve.js";
 
 /** A resolved virtual id: Vite's convention is a leading NUL byte. */
 const resolved = (id) => `\0${id}`;
@@ -113,12 +122,55 @@ function flowPlugin({ routerRoot, appEntry, command }) {
    * hand, which is the part that goes wrong.
    */
   const styles = new Map();
+  /**
+   * The React Compiler findings already reported, so each is said once.
+   *
+   * `uf build` runs Vite twice — once for the browser bundle and once for the
+   * server one — over the same modules, so every finding was made twice and
+   * printed twice. An entry records which environment reported a module's
+   * findings first: a re-transform in *that* environment (a dev server, after
+   * an edit) clears it and reports again, and the other environment's pass over
+   * the same module stays quiet. Keying on the environment rather than on a
+   * flag is what keeps the second half true without making the first half
+   * false.
+   *
+   * @type {Map<string, { environment: string, signatures: Set<string> }>}
+   */
+  const reported = new Map();
+  /** Findings held back as a dependency's, waiting to be counted out loud. */
+  let suppressed = [];
 
   const ensureService = () => {
     service ??= new TransformService({ command, root });
     return service;
   };
 
+  /**
+   * The browser's copy of the route table.
+   *
+   * The manifest is read here rather than once at start-up because `uf dev`
+   * rewrites it whenever the graph moves, and this hook runs again when it
+   * does — a table built from a manifest read at start-up would be the answer
+   * for the project as it was when the server started.
+   *
+   * The count is emitted rather than computed on the Rust side, and that is
+   * the point of it: `uf build` prints what the table it just generated
+   * contains, not what a second implementation of this decision predicted it
+   * would. Only for a build — a dev server has no summary to be true in.
+   */
+  const clientRoutesModule = (table) => {
+    const shipsPage = clientRouteFilter(
+      readRscManifest(process.env[RSC_MANIFEST_ENV]),
+      root,
+      table,
+    );
+    const kept = new Set(table.routes.filter(shipsPage));
+    if (server == null) {
+      emit("rsc-split", { pages: kept.size, routes: table.routes.length });
+    }
+    return routesModuleSource(table, { shipsPage: (route) => kept.has(route) });
+  };
+
   return {
     name: "uf:flow",
     enforce: "pre",
@@ -175,9 +227,16 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       return null;
     },
 
-    load(id) {
+    load(id, loadOptions) {
       if (id === RUNTIME_RESOLVED_ID) return refreshRuntimeSource();
-      if (id === resolved(VIRTUAL.routes)) return routesModuleSource(scanRoutes(appRoot));
+      if (id === resolved(VIRTUAL.routes)) {
+        const table = scanRoutes(appRoot);
+        // The server renders every route, so the server's table is the whole
+        // one and is generated with no filter at all. Only the browser's copy
+        // is split.
+        if (isSsr(this, loadOptions)) return routesModuleSource(table);
+        return clientRoutesModule(table);
+      }
       if (id === resolved(VIRTUAL.client)) return clientModuleSource(entryPath);
       if (id === resolved(VIRTUAL.server)) return serverModuleSource(entryPath);
       if (id.startsWith(STYLE_PREFIX)) return styles.get(id) ?? "";
@@ -194,9 +253,14 @@ function flowPlugin({ routerRoot, appEntry, command }) {
         sourceMap: true,
       });
       if (out == null) return null;
-      for (const diagnostic of out.diagnostics) {
-        this.warn?.(`${diagnostic.function ?? "a function"}: ${diagnostic.message}`);
-      }
+      reportDiagnostics(this, {
+        id: cleanId(id),
+        root,
+        diagnostics: out.diagnostics,
+        environment: ssr ? "ssr" : "client",
+        reported,
+        suppressed,
+      });
       const map = out.map == null ? null : JSON.parse(out.map);
       // StyleX. `uf transform` compiled the module's `stylex.create` calls into
       // class names and handed back the rules they declared; the rules become a
@@ -207,18 +271,34 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       // business: Vite already injects a stylesheet in dev, extracts it in a
       // build, code-splits it per chunk, and replaces it over HMR. A module
       // whose styles are gone stops importing it, and Vite notices.
+      const styled = out.css != null && out.css !== "";
       let output = out.code;
-      if (out.css != null && out.css !== "") {
+      if (styled) {
         const styleId = `${STYLE_PREFIX}${cleanId(id)}.css`;
         styles.set(styleId, out.css);
         output = `import ${JSON.stringify(styleId)};\n${output}`;
       }
-      if (!refresh) return { code: output, map };
+      // A module that compiled a stylesheet has a side effect, whatever its
+      // package says. `@uniflowed/stylex` declares `sideEffects: false` and is
+      // right about its source: `tokens.stylex.js` only exports a token set.
+      // What it exports after this transform is a token set *and* a `:root`
+      // block, and the page that imports `ufTokens` no longer names it at
+      // runtime — the compiler turned every read into the `var(--…)` it minted.
+      // So the import was unused, a side-effect-free module with no used
+      // exports was dropped, and the custom properties every one of those
+      // `var()`s resolves against went with it: rules that referred to nothing.
+      // Declaring the side effect here rather than editing the package is
+      // deliberate — the side effect is one this plugin added, so it is this
+      // plugin's to admit to. See ubugeeei-prod/uf#306.
+      const moduleSideEffects = styled ? true : undefined;
+      if (!refresh) return { code: output, map, moduleSideEffects };
       const relative = path.relative(root, cleanId(id)).split(path.sep).join("/");
-      return addRefreshWrapper(output, map, relative);
+      return { ...addRefreshWrapper(output, map, relative), moduleSideEffects };
     },
 
     buildEnd() {
+      summariseSuppressed(this, suppressed);
+      suppressed = [];
       // A dev server keeps its service for the whole session; a build is
       // done with it here.
       if (server == null) {
@@ -246,9 +326,19 @@ function flowPlugin({ routerRoot, appEntry, command }) {
         service = null;
       });
 
-      // A page or layout appearing or disappearing changes the route table,
+      // A reserved file appearing or disappearing changes the route table,
       // which lives in a virtual module the watcher knows nothing about.
-      const reserved = /\/_uf\.(page|layout|middleware|not-found)(\.[a-z]+)?\.(js|jsx|mdx)$/;
+      //
+      // Built from `RESERVED` rather than written out. It used to be the
+      // literal `(page|layout|middleware|not-found)`, which is a fourth
+      // spelling of a grammar that already has three, and it was already
+      // missing `route` — so adding a route handler to a running dev server
+      // did not rebuild the table and the handler stayed invisible until a
+      // restart. A list that has to match another list has to be that list.
+      const stems = Object.values(RESERVED)
+        .map((stem) => stem.replaceAll(".", "\\."))
+        .join("|");
+      const reserved = new RegExp(`/(${stems})(\\.[a-z]+)?\\.(js|jsx|mdx)$`);
       const onRouteFile = (file) => {
         if (!reserved.test(file) || !file.startsWith(appRoot)) return;
         const routes = devServer.moduleGraph.getModuleById(resolved(VIRTUAL.routes));
@@ -258,6 +348,27 @@ function flowPlugin({ routerRoot, appEntry, command }) {
       devServer.watcher.on("add", onRouteFile);
       devServer.watcher.on("unlink", onRouteFile);
 
+      // The same problem one level up. Adding `"use client"` to a module, or
+      // deleting the import that reached it, changes which routes the browser
+      // is given a page for — and touches no reserved file name, so nothing
+      // above notices. `uf dev` rewrites the RSC manifest when the analysis
+      // moves and only then, so this fires when the answer changed rather than
+      // on every keystroke. Watched explicitly because the file is uf's own
+      // artefact and is in no module graph.
+      const manifestFile = process.env[RSC_MANIFEST_ENV];
+      if (manifestFile != null && manifestFile !== "") {
+        const manifestPath = path.resolve(manifestFile);
+        devServer.watcher.add(manifestPath);
+        const onManifest = (file) => {
+          if (path.resolve(file) !== manifestPath) return;
+          const routes = devServer.moduleGraph.getModuleById(resolved(VIRTUAL.routes));
+          if (routes) devServer.moduleGraph.invalidateModule(routes);
+          devServer.ws.send({ type: "full-reload", path: "*" });
+        };
+        devServer.watcher.on("add", onManifest);
+        devServer.watcher.on("change", onManifest);
+      }
+
       // After Vite's own middlewares, so `/@vite/client`, `/@id/...` and
       // static files are served first and only a document request reaches
       // the renderer.
@@ -266,19 +377,47 @@ function flowPlugin({ routerRoot, appEntry, command }) {
           if (!wantsDocument(request)) return next();
           try {
             const url = request.url ?? "/";
-            const { render } = await importServerEntry(devServer);
-            const result = await render(url, {
-              scripts: [devUrlFor(VIRTUAL.client)],
-              styles: [],
-              preloads: [],
+            const entry = await importServerEntry(devServer);
+            const asRequest = await toRequest(request, devServer.config);
+
+            // One request, owned here and settled once the document has been
+            // written — the same lifecycle `driver.js` gives `uf dev` and
+            // `internal/serve.js` gives `uf preview` and `uf start`. A project
+            // driving Vite itself must not get a different answer about when
+            // `after()` runs than the same project run through `uf dev`; see
+            // `internal/serve.js` and ubugeeei-prod/uf#389.
+            //
+            // Only document requests reach here, so unlike `driver.js` there is
+            // no path where uf hands the response back to Vite's chain: what is
+            // below either writes it or throws.
+            await withRequest(entry, asRequest, async () => {
+              // Before the page: a middleware guards a subtree, and a page
+              // rendered while the guard on it had not run is the whole of
+              // ubugeeei-prod/uf#260. Only document requests reach here, so this
+              // is the page half of the guarantee; `driver.js` makes the same
+              // call above the route handlers, for every method.
+              const guarded = await entry.runMiddleware(asRequest);
+              if (guarded != null) {
+                await send(response, guarded);
+                return;
+              }
+
+              const result = await entry.render(
+                url,
+                { scripts: [devUrlFor(VIRTUAL.client)], styles: [], preloads: [] },
+                { onError: (error) => reportRenderError(devServer, url, error) },
+              );
+              if (result.error != null) reportRenderError(devServer, url, result.error);
+              // Collected rather than piped, for the reason `driver.js` gives at
+              // step 4: `transformIndexHtml` is a whole-document hook.
+              const html = await devServer.transformIndexHtml(url, await result.text());
+              response.statusCode = result.status;
+              response.setHeader("Content-Type", "text/html; charset=utf-8");
+              for (const [name, value] of Object.entries(result.headers ?? {})) {
+                response.setHeader(name, value);
+              }
+              response.end(html);
             });
-            const html = await devServer.transformIndexHtml(url, result.html);
-            response.statusCode = result.status;
-            response.setHeader("Content-Type", "text/html; charset=utf-8");
-            for (const [name, value] of Object.entries(result.headers ?? {})) {
-              response.setHeader(name, value);
-            }
-            response.end(html);
           } catch (error) {
             devServer.ssrFixStacktrace(error);
             next(error);
@@ -344,6 +483,134 @@ function wantsDocument(request) {
   return !/\.[a-z0-9]+$/i.test(pathname);
 }
 
+/** The name of the environment variable that turns every finding back on. */
+const ALL_DIAGNOSTICS = "UF_REACT_COMPILER_DIAGNOSTICS";
+
+/**
+ * Report what the React Compiler said about one module.
+ *
+ * Every finding used to be printed as `a function: <message>` — no file, no
+ * line, no column, and the fallback string doing all the work because the
+ * compiler names an inner function about as often as not. The transform hook
+ * knows the module and the compiler gives a position for most findings, so
+ * both go into the message: Vite prints a plugin warning's `message` and
+ * nothing else, so a location that is not in the string is a location the
+ * reader never sees. `id` and `loc` go along for anything reading the log
+ * object rather than the line. See ubugeeei-prod/uf#307.
+ *
+ * A dependency's findings are held back. A React Compiler bailout inside
+ * `@uniflowed/form` is not something the person running the build can fix, and
+ * a channel carrying forty of them on every build is a channel people stop
+ * reading — which costs them the one finding that was theirs. They are counted
+ * and said once instead, and `UF_REACT_COMPILER_DIAGNOSTICS=all` prints every
+ * one for whoever is fixing the dependency.
+ */
+function reportDiagnostics(context, { id, root, diagnostics, environment, reported, suppressed }) {
+  if (diagnostics.length === 0) return;
+  // A module transformed again by the environment that first reported it has
+  // been edited; anything else is the second bundle passing over the same file.
+  const previous = reported.get(id);
+  const ledger =
+    previous != null && previous.environment !== environment
+      ? previous
+      : { environment, signatures: new Set() };
+  reported.set(id, ledger);
+
+  const file = relativeId(root, id);
+  const mine = isProjectModule(root, id) || process.env[ALL_DIAGNOSTICS] === "all";
+  for (const diagnostic of diagnostics) {
+    // Everything a reader would be shown, so two findings that would print as
+    // the same line collapse into one. The compiler reports "Cannot access refs
+    // during render" once per pass that noticed it — three times for one `ref`
+    // — and three identical lines are not three things to fix.
+    const signature = `${diagnostic.kind}\0${diagnostic.line}\0${diagnostic.column}\0${diagnostic.message}`;
+    if (ledger.signatures.has(signature)) continue;
+    ledger.signatures.add(signature);
+    if (!mine) {
+      suppressed.push(file);
+      continue;
+    }
+    // Two conventions, both honoured. uf's own frames count columns from one
+    // (`uf_term::diagnostic`) and so does every editor a reader will paste
+    // `file:line:column` into; Rollup's `loc.column` counts from zero, which is
+    // what the compiler already gave us. The string gets the reader's number
+    // and the log object gets Rollup's.
+    const at = diagnostic.line == null ? "" : `:${diagnostic.line}:${(diagnostic.column ?? 0) + 1}`;
+    const who = diagnostic.function == null ? "" : ` (in ${diagnostic.function})`;
+    context.warn?.({
+      message: `${file}${at}: ${diagnostic.message}${who}`,
+      id,
+      loc:
+        diagnostic.line == null
+          ? undefined
+          : { file: id, line: diagnostic.line, column: diagnostic.column ?? 0 },
+    });
+  }
+}
+
+/**
+ * Say how many findings were a dependency's, and whose.
+ *
+ * Held back is not the same as hidden: a build that quietly drops forty
+ * findings is a build that has decided for the reader that uf has no bugs. One
+ * line names the packages and how to see the rest.
+ */
+function summariseSuppressed(context, suppressed) {
+  if (suppressed.length === 0) return;
+  const packages = [...new Set(suppressed.map(packageOf))].sort();
+  const count = suppressed.length;
+  context.warn?.(
+    `${count} React Compiler ${count === 1 ? "finding" : "findings"} in ` +
+      `${packages.join(", ")} — not this application's to fix; ` +
+      `set ${ALL_DIAGNOSTICS}=all to see them`,
+  );
+}
+
+/**
+ * Whether a finding about this module is the application author's to act on.
+ *
+ * Inside the project root *and* outside `node_modules`, rather than
+ * `node_modules` alone: uf's own packages reach an application through a
+ * workspace link in this repository and through `node_modules` everywhere
+ * else, and they are no more the reader's code in one case than the other.
+ */
+function isProjectModule(root, id) {
+  const relative = path.relative(root, id);
+  if (relative.startsWith("..") || path.isAbsolute(relative)) return false;
+  return !relative.split(path.sep).includes("node_modules");
+}
+
+/** A module's path as a reader would write it: relative, with forward slashes. */
+function relativeId(root, id) {
+  const relative = path.relative(root, id);
+  return relative === "" ? id : relative.split(path.sep).join("/");
+}
+
+/** The package a module belongs to, for the one line that names them. */
+function packageOf(file) {
+  const parts = file.split("/");
+  const at = parts.lastIndexOf("node_modules");
+  if (at !== -1) {
+    const scoped = parts[at + 1]?.startsWith("@");
+    return parts.slice(at + 1, at + (scoped ? 3 : 2)).join("/");
+  }
+  // No `node_modules` in the path: a workspace link, resolved to a checkout.
+  // The directory the module hangs off is the closest thing to a package name
+  // that is true without reading its `package.json` from a warning path.
+  const up = parts.lastIndexOf("packages");
+  return up === -1 ? parts.slice(0, -1).join("/") || file : parts.slice(up, up + 2).join("/");
+}
+
+/**
+ * Whether a hook is running for the server environment.
+ *
+ * Both spellings, for the reason `transform` above checks both: Vite 6 moved
+ * the answer onto the plugin context and the `ssr` option is the older one.
+ */
+function isSsr(context, options) {
+  return options?.ssr === true || context?.environment?.name === "ssr";
+}
+
 function cleanId(id) {
   const at = id.indexOf("?");
   return at === -1 ? id : id.slice(0, at);

package/internal/events.js

@@ -51,6 +51,26 @@ export function stripAnsi(text) {
   return text.replace(ANSI, "");
 }
 
+/**
+ * Report a page that rendered its error boundary instead of itself.
+ *
+ * `uf dev` has two renderers — the plugin's middleware and the driver's — and
+ * this is the one place either of them says so, because a message written
+ * twice is a message that ends up saying two things. The document the browser
+ * gets is the application's error page, which is what a visitor would see;
+ * the exception belongs in the terminal, which is uf's.
+ *
+ * The stack is mapped back onto the Flow source first, so the frames name the
+ * file that was written rather than the one that was compiled.
+ */
+export function reportRenderError(server, url, error) {
+  if (error instanceof Error) {
+    server.ssrFixStacktrace(error);
+  }
+  const detail = error instanceof Error ? (error.stack ?? error.message) : String(error);
+  server.config.logger.error(`${url} rendered its error boundary\n${stripAnsi(detail)}`);
+}
+
 /**
  * Describe an error for the channel: message, and a location when Babel or
  * Rolldown attached one.

package/internal/http.js

@@ -0,0 +1,79 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// Node's request and response objects on one side, the platform's `Request`
+// and `Response` on the other.
+//
+// uf's server contracts are the platform's — a route handler and a middleware
+// both take a `Request` and return a `Response`, because that is what runs
+// unchanged on Node.js, Bun, Deno and a Cloudflare Worker. Node's dev server
+// speaks `IncomingMessage` and `ServerResponse`, so exactly one place has to
+// translate.
+//
+// It is a module rather than two functions in `driver.js` because there are
+// two dev servers: `driver.js` is what `uf dev` spawns, and the `uf:flow`
+// plugin's own `configureServer` is what a project using Vite directly gets.
+// Both have to run the same middleware before the same request, and a second
+// copy of this translation is how the two would come to disagree about, say,
+// whether a repeated header is joined or appended.
+
+/**
+ * A Node request as a `Request`.
+ *
+ * The body is read as a stream where the host supports it, because a handler
+ * that accepts an upload should not need the whole thing buffered before it
+ * starts.
+ *
+ * @param {import("node:http").IncomingMessage} incoming
+ * @param {{server?: {https?: unknown}} | undefined} config the resolved Vite config
+ */
+export async function toRequest(incoming, config) {
+  const host = incoming.headers.host ?? "localhost";
+  const protocol = config?.server?.https == null ? "http" : "https";
+  const url = new URL(incoming.originalUrl ?? incoming.url ?? "/", `${protocol}://${host}`);
+
+  const headers = new Headers();
+  for (const [name, value] of Object.entries(incoming.headers)) {
+    if (value == null) continue;
+    for (const entry of Array.isArray(value) ? value : [value]) {
+      headers.append(name, entry);
+    }
+  }
+
+  const method = (incoming.method ?? "GET").toUpperCase();
+  const init = { method, headers };
+  if (method !== "GET" && method !== "HEAD") {
+    // `duplex` is required by the specification whenever a body is a stream,
+    // and Node throws without it.
+    init.body = incoming;
+    init.duplex = "half";
+  }
+  return new Request(url, init);
+}
+
+/**
+ * Write a `Response` to a Node response.
+ *
+ * One implementation, reached late. This was a second copy of the loop in
+ * `@uniflowed/server`'s `node.js`, and the two drifted the moment the shared
+ * one moved: `uf start` and every adapter lost the socket pacing and the
+ * hang-up cancel while `uf dev` and `uf preview` kept them, which is a
+ * deployment whose memory profile differs from the one that was checked. See
+ * ubugeeei-prod/uf#400.
+ *
+ * The import is inside the function, and that is not a style choice.
+ * `driver.js` imports this module *statically* and registers the Flow loader
+ * hooks in its own body, so anything reachable from a static import here is
+ * read by Node before there is anything to compile Flow with —
+ * `@uniflowed/server/node` is Flow source, and a static re-export of it makes
+ * every `uf build` die on `import type` with a `SyntaxError`. `loadBuild` in
+ * `internal/serve.js` defers for the same reason and says so.
+ *
+ * @param {import("node:http").ServerResponse} outgoing
+ * @param {Response} result
+ */
+export async function send(outgoing, result) {
+  const { send: write } = await import("@uniflowed/server/node");
+  await write(outgoing, result);
+}