@uniflowed/vite 0.0.0-alpha.18 → 0.0.0-alpha.21

package/index.js

@@ -80,6 +80,7 @@ import {
   RESERVED,
   VIRTUAL,
   clientModuleSource,
+  resolveRouteTarget,
   routesModuleSource,
   scanRoutes,
   serverModuleSource,
@@ -115,6 +116,7 @@ export function devUrlFor(id) {
  * @typedef {object} UniflowedOptions
  * @property {string} [root] absolute project root; Vite's root by default
  * @property {object} [config] the loaded `uf.config.js` object
+ * @property {"web" | "native" | "ios" | "android"} [target] app target
  * @property {string} [command] the `uf` binary to transform through
  */
 
@@ -126,6 +128,7 @@ export function devUrlFor(id) {
 export default function uniflowed(options = {}) {
   const ufConfig = options.config ?? {};
   const app = ufConfig.app ?? {};
+  const routeTarget = resolveRouteTarget(ufConfig, options.target);
   const routerRoot = app.router?.root ?? "app";
   const appEntry = app.router?.entry ?? ufConfig.build?.entries?.[0] ?? "app.js";
   const markdown = app.builtins?.markdown ?? {};
@@ -135,6 +138,20 @@ export default function uniflowed(options = {}) {
   // no `uf.config.js` will mention. It only ever reaches the *development*
   // client entry; see `flowPlugin`'s `load`. ubugeeei-prod/uf#516.
   const strictMode = app.react?.strictMode !== false;
+  // What the browser does with a link, read here for the reason Strict Mode is
+  // and honoured in every command rather than in the build alone: it is the
+  // one setting whose whole effect is what happens on a click, so a dev server
+  // that disagreed with the deployment would be the wrong application to look
+  // at. Anything but `"document"` is the client router, which is what every
+  // project that has not heard of the key has.
+  const navigation = app.rendering?.navigation === "document" ? "document" : "client";
+  // Whether this application starts by attaching to markup or by rendering
+  // into an empty root. `["csr"]` is the only list that means the second, and
+  // `uf` refuses that value beside any other while the config is read — so the
+  // question here is "is it in the list", not "is it the only thing in it",
+  // and a driver started by hand on a config `uf` never validated gets the same
+  // answer for the same reason a project would want.
+  const mount = (app.rendering?.modes ?? []).includes("csr") ? "render" : "hydrate";
 
   const accessibility = ufConfig.accessibility ?? {};
 
@@ -142,7 +159,10 @@ export default function uniflowed(options = {}) {
     flowPlugin({
       routerRoot,
       appEntry,
+      routeTarget,
       strictMode,
+      navigation,
+      mount,
       command: options.command,
       accessibility,
     }),
@@ -157,7 +177,16 @@ export default function uniflowed(options = {}) {
   ];
 }
 
-function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }) {
+function flowPlugin({
+  routerRoot,
+  appEntry,
+  routeTarget,
+  strictMode,
+  navigation,
+  mount,
+  command,
+  accessibility,
+}) {
   let root = process.cwd();
   let isProduction = false;
   /**
@@ -236,10 +265,15 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
     // survives the build — so the browser's table was shipping the absolute
     // path of every page on the machine that built the site, to every visitor.
     // The server's table is read where those files are and keeps them.
-    return routesModuleSource(table, {
-      shipsPage: (route) => kept.has(route),
-      relativeTo: root,
-    });
+    // HTTP handlers are exclusively server capabilities. Even an unused
+    // dynamic import makes Vite traverse the handler's database/auth imports.
+    return routesModuleSource(
+      { ...table, handlers: [] },
+      {
+        shipsPage: (route) => kept.has(route),
+        relativeTo: root,
+      },
+    );
   };
 
   /**
@@ -331,7 +365,10 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
       ensureService();
     },
 
-    resolveId(id) {
+    resolveId(id, importer, resolveOptions) {
+      if (id === "@uniflowed/react" && !isSsr(this, resolveOptions)) {
+        return this.resolve("react", importer, { ...resolveOptions, skipSelf: true });
+      }
       if (id === RUNTIME_PUBLIC_PATH) return RUNTIME_RESOLVED_ID;
       if (id === AUDIT_PUBLIC_PATH) return AUDIT_RESOLVED_ID;
       if (VIRTUAL_IDS.has(id)) return resolved(id);
@@ -346,7 +383,7 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
       if (id === RUNTIME_RESOLVED_ID) return refreshRuntimeSource();
       if (id === AUDIT_RESOLVED_ID) return auditRuntimeSource(accessibility?.axe);
       if (id === resolved(VIRTUAL.routes)) {
-        const table = scanRoutes(appRoot);
+        const table = scanRoutes(appRoot, { target: routeTarget });
         // 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.
@@ -356,8 +393,17 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
       // Strict Mode belongs to the client entry and to development only: a
       // build passes `false`, so the generated module is the one that existed
       // before #516 and a visitor's browser renders once.
+      //
+      // `navigation` is in the same entry and has no `isProduction` beside it,
+      // deliberately: it is what a link does, and a dev server whose links
+      // behave differently from the deployment is the wrong thing to be
+      // looking at. See `clientModuleSource`.
       if (id === resolved(VIRTUAL.client)) {
-        return clientModuleSource(entryPath, { strictMode: strictMode && !isProduction });
+        return clientModuleSource(entryPath, {
+          strictMode: strictMode && !isProduction,
+          navigation,
+          mount,
+        });
       }
       if (id === resolved(VIRTUAL.server)) return serverModuleSource(entryPath);
       // Only `virtual:uf/server` imports this, so it is only ever asked for in
@@ -474,12 +520,13 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
       const tags = [
         {
           tag: "script",
+          attrs: { "data-uf-dev-head-preamble": "react-devtools" },
           children: devtoolsPreamble(),
           injectTo: "head-prepend",
         },
         {
           tag: "script",
-          attrs: { type: "module" },
+          attrs: { type: "module", "data-uf-dev-head-preamble": "react-refresh" },
           children: preambleCode(base),
           injectTo: "head-prepend",
         },
@@ -509,9 +556,8 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
       // 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 escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+      const stems = Object.values(RESERVED).map(escapeRegExp).join("|");
       const reserved = new RegExp(`/(${stems})(\\.[a-z]+)?\\.(js|jsx|mdx)$`);
       const onRouteFile = (file) => {
         if (!reserved.test(file) || !file.startsWith(appRoot)) return;
@@ -562,7 +608,7 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
       // claimed, this one decided, and the other was reached only for what
       // this one declined. Route-handler dispatch was in the other. A
       // `GET /feed` from a browser is `Accept: text/html` with no extension,
-      // so it looked like a document, so `app/feed/_uf.route.js` was never
+      // so it looked like a document, so `app/feed/$route.js` was never
       // asked and the reader got the route table's page — or the not-found
       // page — for a path that had a handler. See ubugeeei-prod/uf#349.
       //
@@ -598,7 +644,7 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
       // list rather than something this middleware can decide on its own.
       return () => {
         // The browser's own reporting channel, mounted above the application
-        // so that a report never reaches a project's `_uf.middleware.js` or
+        // so that a report never reaches a project's `$middleware.js` or
         // its route table. See `internal/diagnostics.js`.
         devServer.middlewares.use(
           createChannelMiddleware((diagnostic) => emit("diagnostic", diagnostic)),
@@ -687,6 +733,30 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
               }
               if (notDocument != null) return false;
 
+              // A single-page project's deployment answers every navigation
+              // with the same empty shell, so this does too. Rendering the
+              // route here instead would have been the better-looking dev
+              // server and the wrong one: a page that only works because the
+              // server rendered it would work all through development and be
+              // blank the day it shipped. It is the same argument
+              // `app.rendering.navigation` makes about a link, one level up.
+              //
+              // The three steps above still ran — the guard, the action, the
+              // handler — and each of them is something `uf build` refuses in
+              // a `["csr"]` project by name. A dev server that skipped them
+              // would hide the very thing the build is going to stop.
+              if (mount === "render") {
+                response.statusCode = 200;
+                response.setHeader("content-type", "text/html; charset=utf-8");
+                const shell = entry.shellDocument({
+                  scripts: [devUrlFor(VIRTUAL.client)],
+                  styles: [],
+                  preloads: [],
+                });
+                response.end(await devServer.transformIndexHtml(url, shell));
+                return true;
+              }
+
               const result = await entry.render(
                 url,
                 { scripts: [devUrlFor(VIRTUAL.client)], styles: [], preloads: [] },
@@ -699,6 +769,22 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
                   // Vite sees the head and only the head. That is what lets the
                   // development server stream like every other host — see below.
                   transformHead: (head) => devServer.transformIndexHtml(url, head),
+                  // And what the streaming actually did, when it changed. The
+                  // router has already decided there is something worth saying
+                  // and written the words — see its `internal/inspector.js`,
+                  // which cannot be imported from here because this file is
+                  // plain JavaScript that Vite loads before any Flow transform
+                  // exists. `info`, because a page that streamed is a
+                  // measurement and not a problem; `origin`, because a report
+                  // that does not say which page produced it is one somebody
+                  // has to reproduce before they can act on it.
+                  onStream: (diagnostic) =>
+                    emit("diagnostic", {
+                      severity: "info",
+                      origin: url,
+                      message: diagnostic.message,
+                      detail: diagnostic.detail,
+                    }),
                 },
               );
               if (result.error != null) reportRenderError(devServer, url, result.error);
@@ -707,7 +793,7 @@ function flowPlugin({ routerRoot, appEntry, strictMode, command, accessibility }
               // `transformIndexHtml` is a *whole document* hook — which made the
               // one place a developer would notice streaming the one place it
               // did not happen: a slow page showed nothing until it was finished
-              // and `_uf.loading.js` looked broken.
+              // and `$loading.js` looked broken.
               //
               // `transformHead` above is the seam. `internal/stream.js` already
               // held the opening chunk back until the head was complete and

package/internal/a11y.js

@@ -86,15 +86,17 @@ export function auditRuntimeSource(settings) {
 /**
  * The tag that loads it, or `null` when this project has no engine.
  *
- * `injectTo: "body"` rather than the head: the audit reads the rendered tree,
- * so there is nothing for it to do until there is one, and a script in the
- * head would only sit through the same wait with the parser stopped behind it.
+ * `injectTo: "head"` because `uf dev` streams the body. Vite's HTML hook only
+ * sees the opening chunk; a `body` injection can land at a React chunk boundary
+ * and split an attribute before the rest of the body arrives. A module in the
+ * head still waits for a settled DOM before auditing — see the runtime — while
+ * staying in markup the opening transform can safely rewrite.
  */
 export function auditTag(base, available) {
   if (!available) return null;
   return {
     tag: "script",
     attrs: { type: "module", src: `${base}${AUDIT_PUBLIC_PATH.slice(1)}` },
-    injectTo: "body",
+    injectTo: "head",
   };
 }

package/internal/config.js

@@ -72,7 +72,7 @@ export async function loadUfConfig(root) {
   }
 
   const compiled = await compileConfig(source, file, root);
-  const module = await import(pathToFileURL(compiled).href);
+  const module = await importConfigModule(compiled);
   const config = module.default;
   if (config == null || typeof config !== "object") {
     throw new Error(
@@ -82,6 +82,20 @@ export async function loadUfConfig(root) {
   return { config, file };
 }
 
+async function importConfigModule(compiled) {
+  const previous = process.env.UF_TRANSFORM_BOOTSTRAP_CONFIG;
+  process.env.UF_TRANSFORM_BOOTSTRAP_CONFIG = "1";
+  try {
+    return await import(pathToFileURL(compiled).href);
+  } finally {
+    if (previous == null) {
+      delete process.env.UF_TRANSFORM_BOOTSTRAP_CONFIG;
+    } else {
+      process.env.UF_TRANSFORM_BOOTSTRAP_CONFIG = previous;
+    }
+  }
+}
+
 /**
  * Transform the config to JavaScript and write it where it can be imported.
  *
@@ -93,8 +107,14 @@ async function compileConfig(source, file, root) {
   const directory = path.join(root, COMPILED_DIR);
   const target = path.join(directory, `uf.config.${hash}.mjs`);
 
-  const out = await transformFlow(source, file, { root, sourceMap: false });
-  const code = rewriteRelativeImports(out?.code ?? source, path.dirname(file));
+  const out = await transformFlow(source, file, {
+    root,
+    sourceMap: false,
+    configBootstrap: true,
+  });
+  const code = rewriteConfigImports(
+    rewriteRelativeImports(out?.code ?? source, path.dirname(file)),
+  );
   // Atomically, because two `uf` commands in one project write this same path
   // at the same time — the hash is of the source, so they agree on the name —
   // and `writeFileSync` truncates before it writes. A reader that caught it
@@ -125,6 +145,13 @@ export function rewriteRelativeImports(code, baseDirectory) {
   );
 }
 
+function rewriteConfigImports(code) {
+  return code.replace(
+    /^\s*import\s*\{\s*defineConfig\s*\}\s*from\s*["']@uniflowed\/config["'];?\n?/gm,
+    "function defineConfig(config) {\n  return config;\n}\n",
+  );
+}
+
 /**
  * The JSON projection of a config object.
  *

package/internal/devtools.js

@@ -23,8 +23,8 @@
 // how the preamble is injected, could have taken it away in a diff nobody would
 // read as being about DevTools. See ubugeeei-prod/uf#503.
 //
-// So the hook is installed here, first, deliberately, and `tests/library/
-// devtools.test.js` runs this script's own text against a fake window.
+// So the hook is installed here, first, deliberately, and `devtools.test.js`
+// beside this package runs this script's own text against a fake window.
 //
 // # Three things DevTools needs, and what carries each
 //

package/internal/diagnostics.js

@@ -57,7 +57,7 @@
 // `@uniflowed/router`'s `internal/diagnostics.js` are the same two strings, and
 // they are the contract. They cannot be *imported* here: this module is loaded
 // by Vite before any Flow transform exists, and both of those are Flow. So they
-// are written out, and `tests/library/dev-channel.test.js` asserts that all
+// are written out, and `packages/vite/dev-channel.test.js` asserts that all
 // four spellings agree — a duplicated constant with a test on it is honest, and
 // one without is how the browser ends up posting to a path nothing serves.
 //
@@ -105,7 +105,7 @@ const SEVERITIES = new Set(["error", "warn", "info"]);
  * The connect middleware that answers the channel.
  *
  * Mounted **before** the application middleware, so a request under `/__uf/`
- * never reaches a project's `_uf.middleware.js` or its route table. A guard
+ * never reaches a project's `$middleware.js` or its route table. A guard
  * that ran for a page's own telemetry would be a guard asked a question the
  * application never asks, and one that redirected it would turn a report into
  * a login page.

package/internal/flow-keywords.js

@@ -435,7 +435,7 @@ export function markLines(lines) {
  *
  * Exported because it is where the decision is visible without starting Shiki:
  * give it the token split a grammar would produce and it says which words it
- * marked. `tests/library/highlight.test.js` uses exactly that, and the splits
+ * marked. `packages/vite/highlight.test.js` uses exactly that, and the splits
  * in it are the ones that had bugs.
  */
 export function markLine(line) {

package/internal/openapi.js

@@ -0,0 +1,218 @@
+// @noflow
+//
+// Route-handler OpenAPI output.
+//
+// The build driver imports this module before it registers the Node Flow
+// hooks, so it must stay plain JavaScript and must not statically import
+// Flow-authored packages. The schema and method vocabulary are loaded inside
+// `createOpenApiDocument`, after the driver has installed the hooks.
+
+const JSON = "application/json";
+const QUERY_EXTENSION = "x-uf-query";
+const STANDARD_METHODS = new Set(["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]);
+
+export async function createOpenApiDocument(handlers, options = {}) {
+  const [{ HANDLER_METHODS }, { toJsonSchema }] = await Promise.all([
+    import("@uniflowed/router/handler"),
+    import("@uniflowed/validator/json-schema"),
+  ]);
+  const paths = {};
+  for (const record of handlers ?? []) {
+    const routePath = openApiPath(record.path);
+    const pathItem = paths[routePath] ?? {};
+    paths[routePath] = pathItem;
+    const module = await loadHandlerModule(record, pathItem);
+    if (module == null) continue;
+    for (const method of implementedMethods(module, HANDLER_METHODS)) {
+      const operation = createOperation(record, method, schemaFor(module, method), toJsonSchema);
+      if (STANDARD_METHODS.has(method)) {
+        pathItem[method.toLowerCase()] = operation;
+      } else if (method === "QUERY") {
+        pathItem[QUERY_EXTENSION] = operation;
+      }
+    }
+  }
+  return {
+    openapi: "3.1.0",
+    info: {
+      title: options.title ?? "uf application",
+      version: options.version ?? "0.0.0",
+    },
+    paths,
+  };
+}
+
+async function loadHandlerModule(record, pathItem) {
+  try {
+    return await record.load();
+  } catch (error) {
+    if (record.file != null) pathItem["x-uf-source"] = record.file;
+    pathItem["x-uf-schema-unavailable"] = errorMessage(error);
+    return null;
+  }
+}
+
+function implementedMethods(module, methods) {
+  return methods.filter(
+    (method) =>
+      typeof module[method] === "function" ||
+      (method === "HEAD" && typeof module.GET === "function"),
+  );
+}
+
+function schemaFor(module, method) {
+  const table = module.schemas;
+  if (!isRecord(table)) return null;
+  const schema = table[method];
+  if (schema == null) return null;
+  if (!isRecord(schema)) {
+    throw new Error(`route handler schemas.${method} must be an object`);
+  }
+  return schema;
+}
+
+function createOperation(record, method, schema, toJsonSchema) {
+  const parameters = pathParameters(record);
+  const operation = {
+    operationId: operationId(record, method),
+    responses: untypedResponses(method),
+  };
+  if (record.file != null) operation["x-uf-source"] = record.file;
+  if (parameters.length > 0) operation.parameters = parameters;
+  if (schema == null) {
+    operation["x-uf-untyped"] = true;
+    return operation;
+  }
+
+  const unrepresentable = [];
+  if (schema.query != null) {
+    addQuerySchema(operation, exportSchema(toJsonSchema, schema.query, "query", unrepresentable));
+  }
+  if (schema.body != null) {
+    operation.requestBody = {
+      required: true,
+      content: {
+        [JSON]: { schema: exportSchema(toJsonSchema, schema.body, "body", unrepresentable) },
+      },
+    };
+  }
+  if (schema.response != null) {
+    operation.responses = {
+      "200": {
+        description: method === "HEAD" ? "Typed response headers" : "Typed response",
+        content:
+          method === "HEAD"
+            ? undefined
+            : {
+                [JSON]: {
+                  schema: exportSchema(toJsonSchema, schema.response, "response", unrepresentable),
+                },
+              },
+      },
+    };
+    if (method === "HEAD") delete operation.responses["200"].content;
+  }
+  if (unrepresentable.length > 0) {
+    operation["x-uf-unrepresentable"] = unrepresentable;
+  }
+  return operation;
+}
+
+function untypedResponses(method) {
+  return {
+    "200": {
+      description: method === "HEAD" ? "Untyped response headers" : "Untyped response",
+    },
+  };
+}
+
+function exportSchema(toJsonSchema, schema, part, unrepresentable) {
+  const exported = toJsonSchema(schema);
+  for (const item of exported.unrepresentable) {
+    unrepresentable.push({ part, path: item.path, kind: item.kind });
+  }
+  return stripDialect(exported.schema);
+}
+
+function addQuerySchema(operation, schema) {
+  if (schema.type !== "object" || !isRecord(schema.properties) || hasOwn(schema, "$defs")) {
+    operation["x-uf-query-schema"] = schema;
+    return;
+  }
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const parameters = Object.keys(schema.properties).map((name) => ({
+    name,
+    in: "query",
+    required: required.has(name),
+    schema: schema.properties[name],
+  }));
+  operation.parameters = [...(operation.parameters ?? []), ...parameters];
+}
+
+function stripDialect(value) {
+  if (Array.isArray(value)) return value.map(stripDialect);
+  if (!isRecord(value)) return value;
+  const out = {};
+  for (const key of Object.keys(value)) {
+    if (key === "$schema") continue;
+    out[key] = stripDialect(value[key]);
+  }
+  return out;
+}
+
+function openApiPath(routePath) {
+  return routePath
+    .split("/")
+    .map((segment) => {
+      if (!segment.startsWith(":")) return segment;
+      return `{${segment.endsWith("*") ? segment.slice(1, -1) : segment.slice(1)}}`;
+    })
+    .join("/");
+}
+
+function pathParameters(record) {
+  const params = record.params ?? paramsFromPath(record.path);
+  return params.map((param) => {
+    const parameter = {
+      name: param.name,
+      in: "path",
+      required: true,
+      schema: { type: "string" },
+    };
+    if (param.catchAll) {
+      parameter.description = "Catch-all route segment, slash-separated in the URL.";
+    }
+    return parameter;
+  });
+}
+
+function paramsFromPath(routePath) {
+  return routePath
+    .split("/")
+    .filter((segment) => segment.startsWith(":"))
+    .map((segment) => ({
+      name: segment.endsWith("*") ? segment.slice(1, -1) : segment.slice(1),
+      catchAll: segment.endsWith("*"),
+    }));
+}
+
+function operationId(record, method) {
+  const name = `${method.toLowerCase()} ${record.path}`;
+  return name
+    .replaceAll(/[^a-zA-Z0-9]+/g, " ")
+    .trim()
+    .replaceAll(/ ([a-zA-Z0-9])/g, (_, char) => char.toUpperCase());
+}
+
+function isRecord(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function hasOwn(value, key) {
+  return Object.prototype.hasOwnProperty.call(value, key);
+}
+
+function errorMessage(error) {
+  if (error instanceof Error) return error.message;
+  return String(error);
+}