@uniflowed/vite 0.0.0-alpha.1

package/internal/refresh.js

@@ -0,0 +1,110 @@
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// React Fast Refresh wiring for `uf dev`. The runtime itself is
+// `./refresh-runtime.js`, Meta's `react-refresh` runtime as simplified by
+// `@vitejs/plugin-react` (MIT); this file is the glue that plugin-react adds
+// around it, kept structurally identical so the two stay comparable:
+//
+// * the runtime is served at `/@react-refresh` as a virtual module;
+// * a preamble installs it on `window` before any component module loads;
+// * every module that registered a component gets a header that points
+//   `$RefreshReg$`/`$RefreshSig$` at this module and a footer that validates
+//   the boundary and enqueues the refresh on `import.meta.hot.accept`.
+
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/** Public URL the refresh runtime is served from. */
+export const RUNTIME_PUBLIC_PATH = "/@react-refresh";
+
+/** The resolved id Vite hands back for the runtime. */
+export const RUNTIME_RESOLVED_ID = "\0uf:react-refresh";
+
+const RUNTIME_SOURCE_PATH = fileURLToPath(new URL("./refresh-runtime.js", import.meta.url));
+
+/** The runtime's source, read once. */
+export function refreshRuntimeSource() {
+  return readFileSync(RUNTIME_SOURCE_PATH, "utf8");
+}
+
+/**
+ * The script every HTML document loads first in development.
+ *
+ * `base` is Vite's `config.base`, so the runtime resolves under a sub-path
+ * deployment as well as at the root.
+ */
+export function preambleCode(base = "/") {
+  return `import { injectIntoGlobalHook } from "${base}${RUNTIME_PUBLIC_PATH.slice(1)}";
+injectIntoGlobalHook(window);
+window.$RefreshReg$ = () => {};
+window.$RefreshSig$ = () => (type) => type;`;
+}
+
+const REFRESH_CONTENT = /\$RefreshReg\$\(/;
+const REACT_CLASS_COMPONENT = /extends\s+(?:React\.)?(?:Pure)?Component/;
+
+/**
+ * Wrap a transformed module with the Fast Refresh header and footer.
+ *
+ * A module that registered nothing and defines no class component comes back
+ * untouched, so the wrapper never costs a module that has no component in it.
+ * The source map is shifted by the number of lines prepended, which is what
+ * keeps a stack trace pointing at the author's line.
+ */
+export function addRefreshWrapper(code, map, id) {
+  const hasRefresh = REFRESH_CONTENT.test(code);
+  const onlyReactComponent = !hasRefresh && REACT_CLASS_COMPONENT.test(code);
+  if (!hasRefresh && !onlyReactComponent) {
+    return { code, map };
+  }
+
+  const nextMap = typeof map === "string" ? JSON.parse(map) : map;
+  let nextCode = code;
+
+  if (hasRefresh) {
+    nextCode = `let prevRefreshReg;
+let prevRefreshSig;
+
+if (import.meta.hot && !inWebWorker) {
+  if (!window.$RefreshReg$) {
+    throw new Error(
+      "@uniflowed/vite can't detect the Fast Refresh preamble. Something is wrong."
+    );
+  }
+
+  prevRefreshReg = window.$RefreshReg$;
+  prevRefreshSig = window.$RefreshSig$;
+  window.$RefreshReg$ = RefreshRuntime.getRefreshReg(${JSON.stringify(id)});
+  window.$RefreshSig$ = RefreshRuntime.createSignatureFunctionForTransform;
+}
+
+${nextCode}
+
+if (import.meta.hot && !inWebWorker) {
+  window.$RefreshReg$ = prevRefreshReg;
+  window.$RefreshSig$ = prevRefreshSig;
+}
+`;
+    if (nextMap) nextMap.mappings = ";".repeat(16) + nextMap.mappings;
+  }
+
+  nextCode = `import * as RefreshRuntime from "${RUNTIME_PUBLIC_PATH}";
+const inWebWorker = typeof WorkerGlobalScope !== 'undefined' && self instanceof WorkerGlobalScope;
+
+${nextCode}
+
+if (import.meta.hot && !inWebWorker) {
+  RefreshRuntime.__hmr_import(import.meta.url).then((currentExports) => {
+    RefreshRuntime.registerExportsForReactRefresh(${JSON.stringify(id)}, currentExports);
+    import.meta.hot.accept((nextExports) => {
+      if (!nextExports) return;
+      const invalidateMessage = RefreshRuntime.validateRefreshBoundaryAndEnqueueUpdate(${JSON.stringify(id)}, currentExports, nextExports);
+      if (invalidateMessage) import.meta.hot.invalidate(invalidateMessage);
+    });
+  });
+}
+`;
+  if (nextMap) nextMap.mappings = ";;;" + nextMap.mappings;
+
+  return { code: nextCode, map: nextMap };
+}

package/internal/routes.js

@@ -0,0 +1,243 @@
+// Plain JavaScript: executed by the host that runs Vite, before any transform.
+//
+// The file-system router, as the build sees it.
+//
+// This mirrors `uf_router` in Rust — the same reserved-name grammar
+// (`_uf.<role>[.<variant>].js`, plus `.mdx` for pages), the same route path
+// syntax (`[param]`, `[...rest]`, `(group)`) and the same sort order — and it
+// must keep mirroring it: `uf lint` and `router.js`'s generated types describe
+// the routes this module serves, so the two cannot be allowed to disagree.
+//
+// Everything produced here is a string of JavaScript for a virtual module. The
+// route table imports every page and layout lazily, so a route is a chunk of
+// its own and the client only downloads what it navigates to.
+
+import { readdirSync, statSync } from "node:fs";
+import path from "node:path";
+
+/** The file names the router reserves inside the router root. */
+export const RESERVED = Object.freeze({
+  layout: "_uf.layout",
+  page: "_uf.page",
+  middleware: "_uf.middleware",
+  notFound: "_uf.not-found",
+});
+
+/** Extensions a page or layout may use; `.mdx` is a page written as content. */
+const PAGE_EXTENSIONS = [".js", ".jsx", ".mdx"];
+const MODULE_EXTENSIONS = [".js", ".jsx"];
+
+/** Deepest directory nesting the scan will follow. */
+const MAX_DEPTH = 32;
+
+/**
+ * One route in the table.
+ *
+ * @typedef {object} Route
+ * @property {string} path route path such as `/docs/:slug`
+ * @property {string} pattern the same path with `*` for catch-alls, for humans
+ * @property {ReadonlyArray<{name: string, catchAll: boolean}>} params
+ * @property {string} page absolute path of the page module
+ * @property {ReadonlyArray<string>} layouts absolute paths, root first
+ * @property {ReadonlyArray<string>} middleware absolute paths, root first
+ * @property {boolean} mdx whether the page is MDX content
+ */
+
+/**
+ * Scan `appRoot` for routes.
+ *
+ * Returns routes sorted by path, which is the order `uf_router` uses too.
+ * Directories that do not exist yield an empty table rather than an error: a
+ * library project has no router root, and that is not a mistake.
+ *
+ * @param {string} appRoot absolute path of the router root (`app/`)
+ * @returns {Route[]}
+ */
+export function scanRoutes(appRoot) {
+  const routes = [];
+  let notFound = null;
+  if (!isDirectory(appRoot)) return { routes, notFound };
+
+  const walk = (directory, segments, layouts, middleware, depth) => {
+    if (depth > MAX_DEPTH) return;
+    const entries = readdirSync(directory, { withFileTypes: true }).sort((a, b) =>
+      a.name < b.name ? -1 : a.name > b.name ? 1 : 0,
+    );
+
+    const ownLayout = findModule(directory, RESERVED.layout, MODULE_EXTENSIONS);
+    const ownMiddleware = findModule(directory, RESERVED.middleware, MODULE_EXTENSIONS);
+    const nextLayouts = ownLayout ? [...layouts, ownLayout] : layouts;
+    const nextMiddleware = ownMiddleware ? [...middleware, ownMiddleware] : middleware;
+
+    const page = findModule(directory, RESERVED.page, PAGE_EXTENSIONS);
+    if (page) {
+      const { path: routePath, pattern, params } = routeFromSegments(segments);
+      routes.push({
+        path: routePath,
+        pattern,
+        params,
+        page,
+        layouts: nextLayouts,
+        middleware: nextMiddleware,
+        mdx: page.endsWith(".mdx"),
+      });
+    }
+    if (depth === 0) {
+      const own = findModule(directory, RESERVED.notFound, PAGE_EXTENSIONS);
+      if (own) notFound = { page: own, layouts: nextLayouts, mdx: own.endsWith(".mdx") };
+    }
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      // A leading dot or underscore is private to the author: `_components/`
+      // beside a page is a place to put things, not a route.
+      if (entry.name.startsWith(".") || entry.name.startsWith("_")) continue;
+      walk(
+        path.join(directory, entry.name),
+        [...segments, entry.name],
+        nextLayouts,
+        nextMiddleware,
+        depth + 1,
+      );
+    }
+  };
+
+  walk(appRoot, [], [], [], 0);
+  routes.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  return { routes, notFound };
+}
+
+function isDirectory(candidate) {
+  try {
+    return statSync(candidate).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function findModule(directory, stem, extensions) {
+  for (const extension of extensions) {
+    const candidate = path.join(directory, stem + extension);
+    try {
+      if (statSync(candidate).isFile()) return candidate;
+    } catch {
+      // keep looking
+    }
+  }
+  return null;
+}
+
+/**
+ * Turn directory segments into a route path and its parameters.
+ *
+ * `(group)` segments organise files without appearing in the URL, `[name]`
+ * captures one segment, and `[...name]` captures the rest of the path.
+ */
+export function routeFromSegments(segments) {
+  const params = [];
+  const out = [];
+  for (const segment of segments) {
+    if (segment.startsWith("(") && segment.endsWith(")")) continue;
+    if (segment.startsWith("[...") && segment.endsWith("]")) {
+      const name = segment.slice(4, -1);
+      params.push({ name, catchAll: true });
+      out.push(`:${name}*`);
+      continue;
+    }
+    if (segment.startsWith("[") && segment.endsWith("]")) {
+      const name = segment.slice(1, -1);
+      params.push({ name, catchAll: false });
+      out.push(`:${name}`);
+      continue;
+    }
+    out.push(segment);
+  }
+  const routePath = out.length === 0 ? "/" : `/${out.join("/")}`;
+  return { path: routePath, pattern: routePath.replace(/:(\w+)\*/g, "*$1"), params };
+}
+
+/** Virtual module ids the router plugin serves. */
+export const VIRTUAL = Object.freeze({
+  routes: "virtual:uf/routes",
+  client: "virtual:uf/client",
+  server: "virtual:uf/server",
+});
+
+/**
+ * The source of `virtual:uf/routes`.
+ *
+ * Each page and layout is a lazy `import()`, so a route is a chunk of its own.
+ * 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
+ */
+export function routesModuleSource(table) {
+  const layoutIds = new Map();
+  const layoutImports = [];
+  const layoutId = (file) => {
+    let id = layoutIds.get(file);
+    if (id === undefined) {
+      id = `layout${layoutIds.size}`;
+      layoutIds.set(file, id);
+      layoutImports.push(`const ${id} = () => import(${JSON.stringify(file)});`);
+    }
+    return id;
+  };
+
+  const entries = table.routes.map((route) => {
+    const layouts = route.layouts.map(layoutId);
+    return `  {
+    path: ${JSON.stringify(route.path)},
+    params: ${JSON.stringify(route.params)},
+    mdx: ${route.mdx},
+    file: ${JSON.stringify(route.page)},
+    page: () => import(${JSON.stringify(route.page)}),
+    layouts: [${layouts.join(", ")}],
+  }`;
+  });
+
+  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";
+
+  return `${layoutImports.join("\n")}
+export const routes = [
+${entries.join(",\n")}
+];
+export const notFound = ${notFound};
+export default routes;
+`;
+}
+
+/**
+ * The source of `virtual:uf/client`: hydrate the document with the app.
+ *
+ * The current route's modules are loaded *before* hydration so the first
+ * render is synchronous and matches the server's HTML; a lazy import during
+ * hydration would suspend and React would fall back to a client render.
+ */
+export function clientModuleSource(appEntry) {
+  return `import { hydrate } from "@uniflowed/router/client";
+import { routes, notFound } from ${JSON.stringify(VIRTUAL.routes)};
+import App from ${JSON.stringify(appEntry)};
+hydrate({ App, routes, notFound });
+`;
+}
+
+/**
+ * The source of `virtual:uf/server`: render one URL to HTML.
+ */
+export function serverModuleSource(appEntry) {
+  return `import { createRenderer } from "@uniflowed/router/server";
+import { routes, notFound } from ${JSON.stringify(VIRTUAL.routes)};
+import App from ${JSON.stringify(appEntry)};
+export { routes, notFound };
+export const render = createRenderer({ App, routes, notFound });
+`;
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@uniflowed/vite",
+  "version": "0.0.0-alpha.1",
+  "description": "Vite, driven by uf.config.js: every Flow module through `uf transform`, MDX, the file-system router and static rendering as Vite plugins.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/vite"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./driver": "./driver.js",
+    "./register": "./register.js",
+    "./bun-preload": "./bun-preload.js",
+    "./transform": "./transform.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.js",
+    "driver.js",
+    "register.js",
+    "bun-preload.js",
+    "transform.js",
+    "internal"
+  ],
+  "dependencies": {
+    "@mdx-js/rollup": "^3.1.1",
+    "rehype-slug": "^6.0.0",
+    "remark-frontmatter": "^5.0.0",
+    "remark-gfm": "^4.0.1",
+    "remark-mdx-frontmatter": "^5.2.0",
+    "vite": "^8.2.2"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  }
+}

package/register.js

@@ -0,0 +1,11 @@
+// Plain JavaScript: this file registers the loader, so it cannot need one.
+//
+// `node --import @uniflowed/vite/register app.js` runs a Flow project on
+// Node.js without a build step. Importing this module installs the hooks in
+// `./internal/node-hooks.js` for the rest of the process.
+
+import { register } from "node:module";
+
+register("./internal/node-hooks.js", import.meta.url, {
+  data: { root: process.env.UF_PROJECT_ROOT ?? process.cwd() },
+});

package/transform.js

@@ -0,0 +1,187 @@
+// Plain JavaScript: executed by the host that runs Vite, before any transform
+// exists — this module is how the transform is reached, so it cannot be Flow.
+//
+// The Flow → JavaScript transform lives in `uf` itself (`crates/uf_transform`:
+// the official Flow parser, Flow's own lowering rules, the official React
+// Compiler, oxc for JSX and code generation). This module is the JavaScript
+// side of the `uf transform` service: one long-lived `uf` process per host
+// process, newline-delimited JSON in, replies in request order out.
+//
+// Every host that runs Flow — the Vite plugin, the Node loader hook, the Bun
+// preload, the config loader — goes through here, which is what makes them
+// all produce the same module from the same source.
+
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+
+/** File extensions uf treats as Flow source. */
+export const FLOW_EXTENSIONS = [".js", ".jsx", ".mjs", ".cjs"];
+
+/**
+ * Whether uf is responsible for transforming this module.
+ *
+ * Mirrors `uf_transform::is_flow_module`, and must keep mirroring it: a `uf
+ * dev` session and a `uf test` run that disagree about which files are Flow
+ * disagree about what the code is.
+ *
+ * A build driver synthesises modules of its own (`\0vite/client`, Rolldown's
+ * shims), and a third-party dependency ships JavaScript that is already
+ * JavaScript; neither is Flow. `@uniflowed/*` under `node_modules` is the
+ * deliberate exception: those packages ship Flow source, because that is what
+ * uf tells everyone to write.
+ */
+export function isFlowModule(id) {
+  if (id.startsWith("\0")) return false;
+  const clean = stripQuery(id);
+  if (!FLOW_EXTENSIONS.some((extension) => clean.endsWith(extension))) return false;
+  const at = clean.lastIndexOf("/node_modules/");
+  return at === -1 || clean.slice(at).startsWith("/node_modules/@uniflowed/");
+}
+
+function stripQuery(id) {
+  const at = id.indexOf("?");
+  return at === -1 ? id : id.slice(0, at);
+}
+
+/**
+ * The `uf` binary to talk to.
+ *
+ * `uf dev`, `uf build` and `uf test` set `UF_BINARY` to themselves when they
+ * start a host, so the host reaches exactly the binary that started it. A host
+ * started by hand finds `uf` on PATH, which is what the installer arranges.
+ */
+export function ufBinary() {
+  return process.env.UF_BINARY ?? "uf";
+}
+
+/**
+ * An error the transform reported for one module, with its position when
+ * the parser or the lowering rules gave one.
+ */
+export class TransformError extends Error {
+  constructor(id, message, line, column) {
+    super(message);
+    this.name = "TransformError";
+    this.id = id;
+    this.loc = line != null ? { file: id, line, column: column ?? 0 } : undefined;
+  }
+}
+
+/**
+ * One `uf transform` process, with requests answered in the order they were
+ * sent.
+ *
+ * `uf transform` replies once per request, in order, so a plain queue of
+ * resolvers pairs a reply with its caller — no correlation ids and no map to
+ * leak. Any exit is final: a request made after the process has gone is
+ * rejected at once rather than queued against something that will never
+ * answer.
+ */
+export class TransformService {
+  #child;
+  #pending = [];
+  #failure = null;
+
+  /**
+   * @param {object} [options]
+   * @param {string} [options.command] the `uf` binary; `ufBinary()` by default
+   * @param {string} [options.root] project root, so `uf.config.js` is found
+   */
+  constructor(options = {}) {
+    const command = options.command ?? ufBinary();
+    const root = options.root ?? process.cwd();
+    this.#child = spawn(command, ["--cwd", root, "transform"], {
+      stdio: ["pipe", "pipe", "inherit"],
+    });
+
+    createInterface({ input: this.#child.stdout }).on("line", (line) => {
+      const waiting = this.#pending.shift();
+      if (!waiting) return;
+      let reply;
+      try {
+        reply = JSON.parse(line);
+      } catch {
+        waiting.reject(new Error(`uf transform sent a malformed reply: ${line}`));
+        return;
+      }
+      if (reply.error != null) {
+        waiting.reject(new TransformError(waiting.id, reply.error, reply.line, reply.column));
+        return;
+      }
+      waiting.resolve(reply);
+    });
+
+    this.#child.on("error", (error) => {
+      this.#settleAll(new Error(`could not run \`${command} transform\`: ${error.message}`));
+    });
+    this.#child.on("close", (code) => {
+      this.#settleAll(new Error(`uf transform exited (${code})`));
+    });
+  }
+
+  #settleAll(error) {
+    this.#failure = error;
+    while (this.#pending.length > 0) this.#pending.shift().reject(error);
+  }
+
+  /**
+   * Transform one module.
+   *
+   * Resolves to `{ code, map, diagnostics }`, or to `null` when the module is
+   * not uf's to transform (see `isFlowModule`). Rejects with a
+   * `TransformError` carrying the position when the source is not valid Flow.
+   *
+   * @param {string} id absolute path, used for the map and for errors
+   * @param {string} code the Flow source
+   * @param {object} [options]
+   * @param {boolean} [options.development] readable output, `jsxDEV`
+   * @param {boolean} [options.refresh] Fast Refresh registrations (development only)
+   * @param {boolean} [options.sourceMap] produce a source map; on by default
+   */
+  transform(id, code, options = {}) {
+    if (this.#failure) return Promise.reject(this.#failure);
+    return new Promise((resolve, reject) => {
+      this.#pending.push({
+        id,
+        reject,
+        resolve: (reply) => {
+          if (reply.code == null) {
+            resolve(null);
+            return;
+          }
+          resolve({ code: reply.code, map: reply.map ?? null, diagnostics: reply.diagnostics ?? [] });
+        },
+      });
+      this.#child.stdin.write(`${JSON.stringify({ id, code, options })}\n`);
+    });
+  }
+
+  /** Stop the process. Outstanding requests are rejected. */
+  close() {
+    this.#child.stdin.end();
+    this.#child.kill();
+  }
+}
+
+let shared = null;
+
+/**
+ * The process-wide service, started on first use.
+ *
+ * The loader hooks and the config loader share one process per host rather
+ * than one per module; it lives as long as the host does.
+ */
+export function sharedService(root) {
+  shared ??= new TransformService({ root: root ?? process.env.UF_PROJECT_ROOT ?? process.cwd() });
+  return shared;
+}
+
+/**
+ * Transform one Flow module through the shared service.
+ *
+ * Returns `{ code, map, diagnostics }`; a module that is not uf's to transform
+ * comes back as `null`.
+ */
+export function transformFlow(code, filename, options = {}) {
+  return sharedService(options.root).transform(filename, code, options);
+}