@uniflowed/host 0.0.0-alpha.2

package/bun-preload.js

@@ -0,0 +1,24 @@
+// @noflow
+//
+// Plain JavaScript: this file registers the loader, so it cannot need one.
+//
+// `bun --preload @uniflowed/vite/bun-preload app.js` runs a Flow project on
+// Bun without a build step, through Bun's own plugin API: every module uf is
+// responsible for is transformed by `uf transform` as Bun loads it. It is the
+// Bun counterpart of `./register.js`, and the policy of which files count is
+// the same `isFlowModule`.
+
+import { isFlowModule, transformFlow } from "./transform.js";
+
+Bun.plugin({
+  name: "uniflowed-flow",
+  setup(build) {
+    build.onLoad({ filter: /\.(js|jsx|mjs)$/ }, async (args) => {
+      if (!isFlowModule(args.path)) return undefined;
+      const source = await Bun.file(args.path).text();
+      const out = await transformFlow(source, args.path, { development: true, sourceMap: false });
+      if (out == null) return undefined;
+      return { contents: out.code, loader: "js" };
+    });
+  },
+});

package/internal/node-hooks.js

@@ -0,0 +1,113 @@
+// @noflow
+//
+// Plain JavaScript: this *is* the loader, so it cannot be Flow.
+//
+// Node.js module customization hooks that transform Flow on import.
+//
+// Registered by `@uniflowed/host/register` (through `node:module`'s
+// `register()`), which makes `node --import @uniflowed/host/register app.js`
+// run a Flow project directly: every `.js` module uf is responsible for is
+// transformed as it is loaded through `uf transform`, and everything else is
+// left to Node.
+//
+// Transforms are cached on disk under `.uf/cache/transform/` keyed by a hash
+// of the source, so a second run of the same file is a read rather than a
+// round trip. The cache is content-addressed: an edited file hashes
+// differently, so there is no invalidation to get wrong.
+
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { isFlowModule, transformFlow } from "../transform.js";
+
+/**
+ * Write `contents` to `target` so a concurrent reader never sees half of it.
+ *
+ * `uf test` runs one of these processes per core and they all import the same
+ * few modules at once, so two writers and a reader meet on the same cache
+ * entry constantly. `writeFileSync` is not atomic — a reader can observe a
+ * truncated file and report a module that "does not provide an export" — so
+ * the content goes to a private temporary name first and is then renamed,
+ * which is atomic within a filesystem.
+ *
+ * A failure here is not a failure: a read-only checkout still runs, just
+ * without the cache.
+ */
+function writeAtomically(target, contents) {
+  const temporary = `${target}.${process.pid}.${Math.random().toString(36).slice(2)}`;
+  try {
+    mkdirSync(cacheDirectory, { recursive: true });
+    writeFileSync(temporary, contents);
+    renameSync(temporary, target);
+  } catch {
+    try {
+      unlinkSync(temporary);
+    } catch {
+      // Nothing to clean up.
+    }
+  }
+}
+
+/** Bumped whenever the transform's output shape changes, to retire old entries. */
+const CACHE_VERSION = "2";
+
+let cacheDirectory = null;
+let root = null;
+
+/**
+ * Called once by `register()` with `{ root }`; the cache lives under it and
+ * the transform service is started there so it reads the right config.
+ */
+export async function initialize(data) {
+  root = data?.root ?? process.cwd();
+  cacheDirectory = path.join(root, ".uf", "cache", "transform");
+}
+
+/**
+ * The `load` hook: transform Flow modules, defer everything else.
+ */
+export async function load(url, context, nextLoad) {
+  if (!url.startsWith("file:")) return nextLoad(url, context);
+  const filename = fileURLToPath(url);
+  if (!isFlowModule(filename)) return nextLoad(url, context);
+
+  const source = readFileSync(filename, "utf8");
+  const code = await cachedTransform(source, filename);
+  if (code == null) return nextLoad(url, context);
+  // uf projects are ES modules. Forcing the format here means a project whose
+  // package.json forgot `"type": "module"` still runs, rather than failing on
+  // an `import` in what Node would have guessed was CommonJS.
+  return { format: "module", source: code, shortCircuit: true };
+}
+
+async function cachedTransform(source, filename) {
+  const key = createHash("sha256")
+    .update(CACHE_VERSION)
+    .update("\0")
+    .update(filename)
+    .update("\0")
+    .update(source)
+    .digest("hex");
+  const entry = cacheDirectory ? path.join(cacheDirectory, `${key}.mjs`) : null;
+
+  if (entry) {
+    try {
+      return readFileSync(entry, "utf8");
+    } catch {
+      // not cached yet
+    }
+  }
+
+  const out = await transformFlow(source, filename, { root, development: true, sourceMap: true });
+  if (out == null) return null;
+  const output = out.map
+    ? `${out.code}\n//# sourceMappingURL=data:application/json;base64,${Buffer.from(out.map).toString("base64")}\n`
+    : out.code;
+
+  if (entry) {
+    writeAtomically(entry, output);
+  }
+  return output;
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@uniflowed/host",
+  "version": "0.0.0-alpha.2",
+  "description": "Running Flow on a Capability JS Host, with no bundler in the way.",
+  "type": "module",
+  "license": "MIT",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ubugeeei-prod/uf.git",
+    "directory": "packages/host"
+  },
+  "exports": {
+    "./register": "./register.js",
+    "./bun-preload": "./bun-preload.js",
+    "./transform": "./transform.js",
+    "./internal/node-hooks.js": "./internal/node-hooks.js"
+  },
+  "files": [
+    "register.js",
+    "bun-preload.js",
+    "transform.js",
+    "internal/*.js"
+  ]
+}

package/register.js

@@ -0,0 +1,13 @@
+// @noflow
+//
+// Plain JavaScript: this file registers the loader, so it cannot need one.
+//
+// `node --import @uniflowed/host/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,197 @@
+// @noflow
+//
+// 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 tool synthesises modules of its own — ids beginning with a NUL byte,
+ * a bundler'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.
+ *
+ * Which build tool is deliberately not named. This loader runs Flow on a
+ * Capability JS Host and has no bundler in it; naming one would tie the answer
+ * to a tool that is not in this file's dependency graph.
+ */
+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);
+}