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

package/index.js

@@ -30,6 +30,7 @@ import path from "node:path";
 import mdx from "@mdx-js/rollup";
 import rehypeSlug from "rehype-slug";
 
+import { reportRenderError } from "./internal/events.js";
 import { highlightPlugin } from "./internal/highlight.js";
 import remarkFrontmatter from "remark-frontmatter";
 import remarkGfm from "remark-gfm";
@@ -43,6 +44,7 @@ import {
   refreshRuntimeSource,
 } from "./internal/refresh.js";
 import {
+  RESERVED,
   VIRTUAL,
   clientModuleSource,
   routesModuleSource,
@@ -113,6 +115,23 @@ 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 });
@@ -194,9 +213,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 +231,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 +286,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));
@@ -272,6 +322,7 @@ function flowPlugin({ routerRoot, appEntry, command }) {
               styles: [],
               preloads: [],
             });
+            if (result.error != null) reportRenderError(devServer, url, result.error);
             const html = await devServer.transformIndexHtml(url, result.html);
             response.statusCode = result.status;
             response.setHeader("Content-Type", "text/html; charset=utf-8");
@@ -344,6 +395,124 @@ 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("/");
+}
+
 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/routes.js

@@ -23,6 +23,7 @@ export const RESERVED = Object.freeze({
   page: "_uf.page",
   middleware: "_uf.middleware",
   notFound: "_uf.not-found",
+  error: "_uf.error",
   route: "_uf.route",
 });
 
@@ -56,6 +57,38 @@ const MAX_DEPTH = 32;
  * @property {string} module absolute path of the handler module
  */
 
+/**
+ * One not-found boundary — the page a path under `path` gets when nothing
+ * there matched.
+ *
+ * A `_uf.not-found.js` is a segment file like `_uf.layout.js`, so a directory
+ * declares the 404 for everything beneath it and the resolver takes the
+ * nearest one above the path. `layouts` are the layouts in scope *at that
+ * directory*, which is what wraps the boundary when it renders.
+ *
+ * @typedef {object} NotFoundBoundary
+ * @property {string} path route path of the directory that declares it
+ * @property {string} page absolute path of the page module
+ * @property {ReadonlyArray<string>} layouts absolute paths, root first
+ * @property {boolean} mdx whether the page is MDX content
+ */
+
+/**
+ * One error boundary — what renders in place of the subtree under `path` when
+ * something in it throws.
+ *
+ * The same nearest-ancestor shape as a not-found boundary, and deliberately
+ * not the same extensions: an error module is handed an error and a `reset`,
+ * which is a component's contract. `.mdx` compiles to a component that takes
+ * no such thing, so a `_uf.error.mdx` would be a file the router loads and can
+ * never hand its arguments to.
+ *
+ * @typedef {object} ErrorBoundary
+ * @property {string} path route path of the directory that declares it
+ * @property {string} module absolute path of the error module
+ * @property {ReadonlyArray<string>} layouts absolute paths, root first
+ */
+
 /**
  * Scan `appRoot` for routes.
  *
@@ -64,13 +97,14 @@ const MAX_DEPTH = 32;
  * library project has no router root, and that is not a mistake.
  *
  * @param {string} appRoot absolute path of the router root (`app/`)
- * @returns {Route[]}
+ * @returns {{routes: Route[], handlers: Handler[], notFound: NotFoundBoundary[], errors: ErrorBoundary[]}}
  */
 export function scanRoutes(appRoot) {
   const routes = [];
   const handlers = [];
-  let notFound = null;
-  if (!isDirectory(appRoot)) return { routes, handlers, notFound };
+  const notFound = [];
+  const errors = [];
+  if (!isDirectory(appRoot)) return { routes, handlers, notFound, errors };
 
   const walk = (directory, segments, layouts, middleware, depth) => {
     if (depth > MAX_DEPTH) return;
@@ -105,9 +139,29 @@ export function scanRoutes(appRoot) {
       handlers.push({ path: routePath, pattern, params, module: handler });
     }
 
-    if (depth === 0) {
-      const own = findModule(directory, RESERVED.notFound, PAGE_EXTENSIONS);
-      if (own) notFound = { page: own, layouts: nextLayouts, mdx: own.endsWith(".mdx") };
+    // At every depth, not only the root. This read `if (depth === 0)`, so
+    // `app/guide/_uf.not-found.js` was never looked for and a reader who
+    // followed a stale link into the manual was answered by the site's root
+    // 404, outside the manual's own layout. See ubugeeei-prod/uf#263.
+    const ownNotFound = findModule(directory, RESERVED.notFound, PAGE_EXTENSIONS);
+    if (ownNotFound) {
+      notFound.push({
+        path: routeFromSegments(segments).path,
+        page: ownNotFound,
+        layouts: nextLayouts,
+        mdx: ownNotFound.endsWith(".mdx"),
+      });
+    }
+
+    // `errors` is the boundaries a project declares, not failures that
+    // happened: one entry per directory holding an `_uf.error.js`.
+    const ownError = findModule(directory, RESERVED.error, MODULE_EXTENSIONS);
+    if (ownError) {
+      errors.push({
+        path: routeFromSegments(segments).path,
+        module: ownError,
+        layouts: nextLayouts,
+      });
     }
 
     for (const entry of entries) {
@@ -129,7 +183,20 @@ export function scanRoutes(appRoot) {
   const byPath = (a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
   routes.sort(byPath);
   handlers.sort(byPath);
-  return { routes, handlers, notFound };
+  // Sorted by path, not by which is nearest: the resolver picks the longest
+  // path that covers the URL, so it does not depend on this order, and sorting
+  // by nearness would hide that.
+  //
+  // Two boundaries can share a path, because a `(group)` directory is not a URL
+  // segment — `app/_uf.not-found.js` and `app/(marketing)/_uf.not-found.js` are
+  // both at `/`, and the URL cannot say which tree it is in. The sort is stable
+  // and `walk` records a directory's own boundary before descending, so the
+  // shallower file wins, which is the one that is the site's own 404 rather
+  // than one section's idea of it. Letting each group own a boundary needs the
+  // parallel-route trees uf does not have yet; see ubugeeei-prod/uf#267.
+  notFound.sort(byPath);
+  errors.sort(byPath);
+  return { routes, handlers, notFound, errors };
 }
 
 function isDirectory(candidate) {
@@ -195,7 +262,7 @@ export const VIRTUAL = Object.freeze({
  * Layouts are deduplicated into one table so a layout shared by fifty routes
  * is one dynamic import, not fifty.
  *
- * @param {{routes: Route[], notFound: object | null}} table
+ * @param {{routes: Route[], handlers?: Handler[], notFound?: NotFoundBoundary[], errors?: ErrorBoundary[]}} table
  */
 export function routesModuleSource(table) {
   const layoutIds = new Map();
@@ -222,14 +289,32 @@ export function routesModuleSource(table) {
   }`;
   });
 
-  const notFound = table.notFound
-    ? `{
-  mdx: ${table.notFound.mdx},
-  file: ${JSON.stringify(table.notFound.page)},
-  page: () => import(${JSON.stringify(table.notFound.page)}),
-  layouts: [${table.notFound.layouts.map(layoutId).join(", ")}],
-}`
-    : "null";
+  // A list, because a not-found is a segment file: every directory may declare
+  // one and the router takes the nearest above the path. `layoutId` is the
+  // same table the routes use, so a boundary that shares a layout with a page
+  // shares its dynamic import too.
+  const notFoundEntries = (table.notFound ?? []).map(
+    (boundary) => `  {
+    path: ${JSON.stringify(boundary.path)},
+    mdx: ${boundary.mdx},
+    file: ${JSON.stringify(boundary.page)},
+    page: () => import(${JSON.stringify(boundary.page)}),
+    layouts: [${boundary.layouts.map(layoutId).join(", ")}],
+  }`,
+  );
+
+  // An error boundary is loaded with the route it guards rather than when it
+  // is needed: React decides to render a boundary's fallback synchronously,
+  // during the render that threw, so a module that still has to be imported is
+  // a module that is not there when the only chance to use it arrives.
+  const errorEntries = (table.errors ?? []).map(
+    (boundary) => `  {
+    path: ${JSON.stringify(boundary.path)},
+    file: ${JSON.stringify(boundary.module)},
+    module: () => import(${JSON.stringify(boundary.module)}),
+    layouts: [${boundary.layouts.map(layoutId).join(", ")}],
+  }`,
+  );
 
   // Handlers are a separate table because nothing on the client wants them:
   // a route handler answers a request, so shipping its module to the browser
@@ -250,7 +335,12 @@ ${entries.join(",\n")}
 export const handlers = [
 ${handlerEntries.join(",\n")}
 ];
-export const notFound = ${notFound};
+export const notFound = [
+${notFoundEntries.join(",\n")}
+];
+export const errors = [
+${errorEntries.join(",\n")}
+];
 export default routes;
 `;
 }
@@ -264,9 +354,9 @@ export default routes;
  */
 export function clientModuleSource(appEntry) {
   return `import { hydrate } from "@uniflowed/router/client";
-import { routes, notFound } from ${JSON.stringify(VIRTUAL.routes)};
+import { routes, notFound, errors } from ${JSON.stringify(VIRTUAL.routes)};
 import App from ${JSON.stringify(appEntry)};
-hydrate({ App, routes, notFound });
+hydrate({ App, routes, notFound, errors });
 `;
 }
 
@@ -275,10 +365,10 @@ hydrate({ App, routes, notFound });
  */
 export function serverModuleSource(appEntry) {
   return `import { createDispatcher, createRenderer } from "@uniflowed/router/server";
-import { routes, handlers, notFound } from ${JSON.stringify(VIRTUAL.routes)};
+import { routes, handlers, notFound, errors } from ${JSON.stringify(VIRTUAL.routes)};
 import App from ${JSON.stringify(appEntry)};
-export { routes, handlers, notFound };
-export const render = createRenderer({ App, routes, notFound });
+export { routes, handlers, notFound, errors };
+export const render = createRenderer({ App, routes, notFound, errors });
 export const dispatch = createDispatcher({ handlers });
 `;
 }