@uniflowed/vite 0.0.0-alpha.9 → 0.2.0

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/frontmatter.js

@@ -0,0 +1,33 @@
+// @noflow
+//
+// A document's YAML front matter, as `export const frontmatter`.
+//
+// Plain JavaScript, for the reason `index.js` gives: Vite imports this before
+// any transform runs.
+//
+// This is `remark-mdx-frontmatter` for the one format uf reads, and it replaces
+// that package for one reason. The package imported `toml` 3.0.0 at the top of
+// its module whether or not a document held any TOML, so every project uf
+// scaffolded installed a parser with two high advisories and failed its first
+// `uf audit` (#1009). The TOML half was never reachable from here either:
+// `remark-frontmatter` is given its default, which recognises YAML and nothing
+// else, so a `+++` block was never a front-matter node to parse.
+//
+// For YAML the output is the package's, through the same two helpers it used:
+// the first `yaml` node is parsed and defined as `frontmatter`, and a document
+// with none exports `undefined`.
+
+import { valueToEstree } from "estree-util-value-to-estree";
+import { define } from "unist-util-mdx-define";
+import { parse } from "yaml";
+
+/** The remark plugin: `export const frontmatter` from a document's YAML. */
+export default function remarkFrontmatterExport() {
+  return (tree, file) => {
+    const node = tree.children.find((child) => child.type === "yaml");
+    const data = node == null ? undefined : parse(node.value);
+    define(tree, file, {
+      frontmatter: valueToEstree(data, { preserveReferences: true }),
+    });
+  };
+}

package/internal/http.js

@@ -25,13 +25,18 @@
  * that accepts an upload should not need the whole thing buffered before it
  * starts.
  *
+ * `path` names the path and query to build it at, when that is not the one the
+ * request line carried — `uf dev` passes the one Vite's base middleware has
+ * already taken `app.router.basePath` off.
+ *
  * @param {import("node:http").IncomingMessage} incoming
  * @param {{server?: {https?: unknown}} | undefined} config the resolved Vite config
+ * @param {string} [path]
  */
-export async function toRequest(incoming, config) {
+export async function toRequest(incoming, config, path) {
   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 url = new URL(path ?? incoming.originalUrl ?? incoming.url ?? "/", `${protocol}://${host}`);
 
   const headers = new Headers();
   for (const [name, value] of Object.entries(incoming.headers)) {
@@ -52,6 +57,20 @@ export async function toRequest(incoming, config) {
   return new Request(url, init);
 }
 
+/**
+ * A Node request as a `Request` that carries its address and nothing else.
+ *
+ * For the questions asked about a URL alone — `app.router`'s redirects and
+ * headers, in front of Vite's own middleware — which must not wrap the body a
+ * later middleware turns into the `Request` the application reads.
+ *
+ * @param {import("node:http").IncomingMessage} incoming
+ */
+export function toAddressRequest(incoming) {
+  const host = incoming.headers.host ?? "localhost";
+  return new Request(new URL(incoming.originalUrl ?? incoming.url ?? "/", `http://${host}`));
+}
+
 /**
  * Write a `Response` to a Node response.
  *

package/internal/image-endpoint.js

@@ -0,0 +1,118 @@
+// @noflow
+//
+// Plain JavaScript: executed by the host that serves a build, and by `uf dev`.
+//
+// `/__uf/image` on the three doors `uf` itself runs — `uf dev`, `uf preview`
+// and `uf start` — with `uf` as the encoder.
+//
+// The endpoint is `@uniflowed/server/image`'s, the fetch is
+// `@uniflowed/server/image/node`'s, and this is the one piece those two
+// cannot have: a transformer that reaches the `uf` binary. It writes the
+// bounded source to a private temporary directory, asks `uf assets` for one
+// variant of it (`crates/uf_cli/src/commands/assets.rs`'s `variant` request,
+// which is `uf_assets::variant`), and reads the one file that comes back.
+// Both files are removed before the answer is returned: the cache is the
+// endpoint's `CacheStore`, not this directory.
+//
+// A deployed directory has no `uf` in it, which is why this is not in
+// `@uniflowed/server`. What `--adapter` links instead is argued in
+// `driver.js`'s `imageEndpointSource`.
+
+import { randomUUID } from "node:crypto";
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { AssetService } from "@uniflowed/host/assets";
+
+/**
+ * Whether the project asked for an endpoint at all.
+ *
+ * `app.builtins.images.remotePatterns` with something in it, and images not
+ * turned off. Nothing else constructs one: a project that listed no host has
+ * no `/__uf/image`, and the path is an ordinary 404.
+ *
+ * @param {{enabled?: boolean, remotePatterns?: unknown[]} | undefined} images
+ */
+export function servesRemoteImages(images) {
+  return (
+    images?.enabled !== false &&
+    Array.isArray(images?.remotePatterns) &&
+    images.remotePatterns.length > 0
+  );
+}
+
+/**
+ * The endpoint's options from `app.builtins.images`, with uf's defaults where
+ * the project said nothing — the same defaults `uf_assets::ImagesConfig`
+ * applies, from `@uniflowed/server/image` where both sides can read them.
+ *
+ * @param {object} images `app.builtins.images`
+ * @param {{DEFAULT_WIDTHS: number[], DEFAULT_QUALITY: number}} defaults
+ */
+export function endpointSettings(images, defaults) {
+  return {
+    remotePatterns: images.remotePatterns,
+    widths: images.widths ?? defaults.DEFAULT_WIDTHS,
+    quality: images.quality ?? defaults.DEFAULT_QUALITY,
+    qualities: images.qualities ?? [],
+  };
+}
+
+/**
+ * An encoder that is `uf` itself.
+ *
+ * One `uf assets` process for the life of the server, started on the first
+ * miss and not before, and one temporary directory beside it.
+ *
+ * @param {{root: string, command?: string}} options
+ */
+export function ufImageTransform({ root, command }) {
+  let service = null;
+  let directory = null;
+  return async function transform({ bytes, width, quality, avif }) {
+    service ??= new AssetService({ command, root });
+    directory ??= mkdtemp(path.join(os.tmpdir(), "uf-image-"));
+    const base = path.join(await directory, randomUUID());
+    const source = `${base}.source`;
+    const out = `${base}.out`;
+    await writeFile(source, bytes);
+    try {
+      const variant = await service.variant(source, { outDir: out, width, quality, avif });
+      const encoded = await readFile(path.join(out, variant.file));
+      return {
+        bytes: new Uint8Array(encoded.buffer, encoded.byteOffset, encoded.byteLength),
+        type: variant.mime,
+      };
+    } finally {
+      await rm(source, { force: true });
+      await rm(out, { recursive: true, force: true });
+    }
+  };
+}
+
+/**
+ * `/__uf/image` for a door `uf` runs, or `undefined` for a project with no
+ * remote images.
+ *
+ * `store` is the `CacheStore` a durable `rendering.cache.store` gave the route
+ * cache's provider to, when there is one; without it the endpoint keeps its
+ * variants in memory.
+ *
+ * @param {{images?: object, root: string, command?: string, store?: object}} options
+ */
+export async function localImageEndpoint({ images, root, command, store }) {
+  if (!servesRemoteImages(images)) return undefined;
+  const [endpoint, node] = await Promise.all([
+    import("@uniflowed/server/image"),
+    import("@uniflowed/server/image/node"),
+  ]);
+  return endpoint.createImageEndpoint({
+    ...endpointSettings(images, endpoint),
+    fetch: node.nodeImageFetch({
+      allowPrivateAddresses: images.dangerouslyAllowPrivateAddresses === true,
+    }),
+    transform: ufImageTransform({ root, command }),
+    ...(store == null ? {} : { store }),
+  });
+}

package/internal/instrumentation.js

@@ -0,0 +1,23 @@
+// @noflow
+
+import { existsSync } from "node:fs";
+import path from "node:path";
+
+export function instrumentationFile(root, client = false) {
+  const stem = client ? "$instrumentation.client" : "$instrumentation";
+  const files = [".js", ".jsx"]
+    .map((extension) => path.join(root, stem + extension))
+    .filter(existsSync);
+  if (files.length > 1)
+    throw new Error(`uf: choose one instrumentation module: ${files.join(", ")}`);
+  return files[0] ?? null;
+}
+
+export function clientInstrumentationSource(file) {
+  if (file == null) return "";
+  return `import * as instrumentation from ${JSON.stringify(file)};
+import { installClientInstrumentation } from "@uniflowed/router/instrumentation";
+const disposeInstrumentation = await installClientInstrumentation(instrumentation);
+if (import.meta.hot) import.meta.hot.dispose(disposeInstrumentation);
+`;
+}

package/internal/module-graph.js

@@ -0,0 +1,134 @@
+// @noflow
+//
+// Plain JavaScript: the driver imports it, and the driver runs before any Flow
+// loader exists.
+//
+// The module graph `uf build --analyze` reads: every module each bundle was
+// built from, what it imports, and which chunk its rendered code went into.
+//
+// What the graph means — which route a module belongs to, the chain of imports
+// behind it, what it weighs — is uf's, in `crates/uf_bundle/src/analysis.rs`.
+// This file writes down only what the bundler knows and uf cannot, and that
+// split is the reason the graph is a file at all: a builder other than this
+// one that writes the same file gets the same analysis.
+//
+//   {
+//     "version": 1,
+//     "builds": [{
+//       "environment": "client",
+//       "entries": ["virtual:uf/client"],
+//       "modules": [{ "id": "app/$page.js", "imports": ["app/Counter.js"], "dynamicImports": [] }],
+//       "chunks": [{
+//         "file": "assets/index-3f2a.js",
+//         "facade": "virtual:uf/client",
+//         "modules": [{ "id": "virtual:uf/client", "code": "…" }]
+//       }]
+//     }]
+//   }
+
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+/** Where the driver writes the graph, in the build's metadata directory. */
+export const MODULE_GRAPH_FILE = "uf-module-graph.json";
+
+const VERSION = 1;
+
+/**
+ * A plugin that records the graph of every bundle it takes part in, and the
+ * means to write what it recorded.
+ *
+ * `isReference(file)` says whether an absolute file is a client reference: an
+ * entry the browser loads because a server component named it, rather than on
+ * every page. Its chunk still carries it as the facade, and it is left out of
+ * `entries`, which is the list of what every page of a bundle loads.
+ */
+export function createModuleGraphCollector(root, { isReference = () => false } = {}) {
+  const builds = [];
+  const graph = () => ({ version: VERSION, builds });
+  return {
+    plugin: {
+      name: "uf:module-graph",
+      // Last, so the bundle it reads is one every other plugin has finished.
+      enforce: "post",
+      generateBundle(_options, bundle) {
+        builds.push(describeBundle(this, root, bundle, isReference));
+      },
+    },
+    graph,
+    write(file) {
+      mkdirSync(path.dirname(file), { recursive: true });
+      writeFileSync(file, `${JSON.stringify(graph())}\n`);
+    },
+  };
+}
+
+/** One bundle, as `generateBundle` sees it. */
+function describeBundle(context, root, bundle, isReference) {
+  const ids = typeof context.getModuleIds === "function" ? [...context.getModuleIds()] : [];
+  const modules = ids
+    .map((id) => {
+      const info = context.getModuleInfo(id);
+      return {
+        id: moduleId(root, id),
+        imports: (info?.importedIds ?? []).map((imported) => moduleId(root, imported)),
+        dynamicImports: (info?.dynamicallyImportedIds ?? []).map((imported) =>
+          moduleId(root, imported),
+        ),
+      };
+    })
+    .sort(byKey("id"));
+  const entries = new Set();
+  const chunks = [];
+  for (const output of Object.values(bundle)) {
+    if (output.type !== "chunk") {
+      continue;
+    }
+    const facade = output.isEntry ? (output.facadeModuleId ?? null) : null;
+    if (facade != null && !isReference(facade.split("?")[0])) {
+      entries.add(moduleId(root, facade));
+    }
+    chunks.push({
+      file: output.fileName,
+      facade: facade == null ? null : moduleId(root, facade),
+      // A module the bundler left no code for was still walked through to
+      // reach what it imports, so it stays in `modules` above; it has nothing
+      // to weigh, so it is not in the chunk.
+      modules: Object.entries(output.modules ?? {})
+        .map(([id, rendered]) => ({ id: moduleId(root, id), code: rendered?.code ?? "" }))
+        .filter((module) => module.code !== ""),
+    });
+  }
+  return {
+    environment: context.environment?.name ?? "client",
+    entries: [...entries].sort(),
+    modules,
+    chunks: chunks.sort(byKey("file")),
+  };
+}
+
+/**
+ * A module id as the analysis spells it: relative to the project root with
+ * `/`, without the `\0` a resolved virtual module carries, and with its query.
+ *
+ * Relative even when it climbs out of the root, as a workspace package does,
+ * because an absolute path would make two machines' reports of the same build
+ * disagree.
+ */
+export function moduleId(root, id) {
+  const bare = id.startsWith("\0") ? id.slice(1) : id;
+  const at = bare.indexOf("?");
+  const file = at === -1 ? bare : bare.slice(0, at);
+  if (!path.isAbsolute(file)) {
+    return bare;
+  }
+  const relative = path.relative(root, file);
+  if (path.isAbsolute(relative)) {
+    return bare;
+  }
+  return `${relative.split(path.sep).join("/")}${at === -1 ? "" : bare.slice(at)}`;
+}
+
+function byKey(key) {
+  return (a, b) => (a[key] < b[key] ? -1 : a[key] > b[key] ? 1 : 0);
+}

package/internal/native-web.js

@@ -0,0 +1,26 @@
+// @noflow
+
+import { createRequire } from "node:module";
+import path from "node:path";
+
+/** React Native Web is supplied by the application, including its version. */
+export function nativeWebPlugin(target) {
+  let root = process.cwd();
+  return {
+    name: "uf:react-native-web",
+    enforce: "pre",
+    configResolved(config) {
+      root = config.root;
+    },
+    resolveId(source) {
+      if (target !== "web" || source !== "react-native") return null;
+      try {
+        return createRequire(path.join(root, "package.json")).resolve("react-native-web");
+      } catch {
+        throw new Error(
+          "A shared React Native page needs the application's react-native-web dependency: run `uf add react-native-web`.",
+        );
+      }
+    },
+  };
+}

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);
+}

package/internal/relay.js

@@ -0,0 +1,74 @@
+// @noflow
+import { createRequire } from "node:module";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+/** CommonJS hidden behind uf's excluded Flow packages still needs prebundling. */
+export function relayDependencies(root, server = false) {
+  const require = createRequire(path.join(root, "package.json"));
+  const entries = server
+    ? ["relay-runtime", "relay-runtime/experimental", "react-relay/rsc_EXPERIMENTAL.js"]
+    : ["relay-runtime", "react-relay", "react-relay/rsc-client_EXPERIMENTAL.js"];
+  return entries.filter((entry) => {
+    try {
+      require.resolve(entry);
+      return true;
+    } catch (error) {
+      if (error.code === "MODULE_NOT_FOUND" || error.code === "ERR_PACKAGE_PATH_NOT_EXPORTED")
+        return false;
+      throw error;
+    }
+  });
+}
+
+/** Resolve config from the application, independently of the process's cwd. */
+export async function relayConfig(root) {
+  for (const name of ["relay.config.json", "relay.config.js", "relay.config.mjs"]) {
+    const filename = path.join(root, name);
+    if (!fs.existsSync(filename)) continue;
+    const config = name.endsWith(".json")
+      ? JSON.parse(fs.readFileSync(filename, "utf8"))
+      : (await import(pathToFileURL(filename).href)).default;
+    return artifactOptions(root, config);
+  }
+  const filename = path.join(root, "package.json");
+  const config = fs.existsSync(filename)
+    ? JSON.parse(fs.readFileSync(filename, "utf8")).relay
+    : null;
+  return artifactOptions(root, config);
+}
+
+function artifactOptions(root, config) {
+  if (config?.projects != null) {
+    throw new Error("uf's Relay integration currently needs a single-project Relay config.");
+  }
+  return {
+    artifactDirectory:
+      config?.artifactDirectory == null ? null : path.resolve(root, config.artifactDirectory),
+    eagerEsModules: true,
+    jsModuleFormat: "commonjs",
+    codegenCommand: "uf run relay",
+  };
+}
+
+/** Flow has already lowered components/hooks; Relay owns the GraphQL transform. */
+export async function transformRelay(code, filename, map, options) {
+  if (
+    !code.includes("graphql") ||
+    !/["'](?:@uniflowed\/relay|react-relay|relay-runtime)["']/.test(code)
+  )
+    return null;
+  const [{ transformAsync }, { default: relay }] = await Promise.all([
+    import("@babel/core"),
+    import("babel-plugin-relay"),
+  ]);
+  return transformAsync(code, {
+    filename,
+    babelrc: false,
+    configFile: false,
+    sourceMaps: true,
+    inputSourceMap: map ?? undefined,
+    plugins: [[relay, options]],
+  });
+}