@uniflowed/vite 0.0.0-alpha.4 → 0.0.0-alpha.40

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

@@ -0,0 +1,98 @@
+// @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.
+ *
+ * `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, path) {
+  const host = incoming.headers.host ?? "localhost";
+  const protocol = config?.server?.https == null ? "http" : "https";
+  const url = new URL(path ?? 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);
+}
+
+/**
+ * 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.
+ *
+ * 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);
+}

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