@prismatic-io/lux 0.0.1

package/src/orchestrator/fixture-identity.ts

@@ -0,0 +1,67 @@
+import { lstat, readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import { contentHash, type FixturesRef, valueHash } from "../core/index.js";
+
+export type FixtureIdentity = {
+  rootDir: string;
+  hash: string;
+};
+
+const fixtureEntries = async (
+  rootDir: string,
+): Promise<Array<{ path: string; type: "directory" | "file"; mode: number; hash?: string }>> => {
+  const entries: Array<{
+    path: string;
+    type: "directory" | "file";
+    mode: number;
+    hash?: string;
+  }> = [];
+  const pending = [rootDir];
+  while (pending.length > 0) {
+    const directory = pending.pop();
+    if (!directory) continue;
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      const absolute = join(directory, entry.name);
+      const path = relative(rootDir, absolute);
+      const metadata = await lstat(absolute);
+      if (metadata.isSymbolicLink()) {
+        throw new Error(`fixtures: tree cannot contain symlinks: ${absolute}`);
+      }
+      if (metadata.isDirectory()) {
+        entries.push({ path, type: "directory", mode: metadata.mode & 0o777 });
+        pending.push(absolute);
+      } else if (metadata.isFile()) {
+        entries.push({
+          path,
+          type: "file",
+          mode: metadata.mode & 0o777,
+          hash: contentHash(await readFile(absolute)),
+        });
+      } else {
+        throw new Error(`fixtures: unsupported entry type: ${absolute}`);
+      }
+    }
+  }
+  return entries.sort((a, b) => a.path.localeCompare(b.path));
+};
+
+export const fixtureIdentity = async (
+  ref: FixturesRef,
+  baseDir: string,
+): Promise<FixtureIdentity> => {
+  const fixturePath = typeof ref === "string" ? ref : ref.path;
+  const rootDir = resolve(baseDir, fixturePath);
+  let metadata: Awaited<ReturnType<typeof lstat>>;
+  try {
+    metadata = await lstat(rootDir);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      throw new Error(`fixtures: directory not found: ${rootDir}`);
+    }
+    throw error;
+  }
+  if (metadata.isSymbolicLink() || !metadata.isDirectory()) {
+    throw new Error(`fixtures: expected a real directory: ${rootDir}`);
+  }
+  return { rootDir, hash: valueHash(await fixtureEntries(rootDir)) };
+};

package/src/orchestrator/fs-read.ts

@@ -0,0 +1,126 @@
+import { existsSync } from "node:fs";
+import type { FileHandle } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
+import { join, relative, resolve } from "node:path";
+import type { z } from "zod";
+
+const errorMessage = (error: unknown): string =>
+  error instanceof Error ? error.message : String(error);
+
+/**
+ * Read at most `maxBytes` from an already-open file descriptor. The extra
+ * byte closes the stat/read growth race without ever buffering an unbounded
+ * file.
+ */
+export const readBoundedHandle = async (
+  handle: FileHandle,
+  maxBytes: number,
+  label: string,
+): Promise<Buffer> => {
+  if (!Number.isSafeInteger(maxBytes) || maxBytes < 0) {
+    throw new RangeError("maxBytes must be a non-negative safe integer");
+  }
+  const bytes = Buffer.alloc(maxBytes + 1);
+  let offset = 0;
+  while (offset < bytes.length) {
+    const read = await handle.read(bytes, offset, bytes.length - offset, offset);
+    if (read.bytesRead === 0) break;
+    offset += read.bytesRead;
+  }
+  if (offset > maxBytes) throw new Error(`${label} exceeds ${maxBytes} bytes`);
+  return bytes.subarray(0, offset);
+};
+
+export const parsePersistedJson = <S extends z.ZodType>(
+  path: string,
+  contents: string,
+  schema: S,
+): z.infer<S> => {
+  let value: unknown;
+  try {
+    value = JSON.parse(contents);
+  } catch (error) {
+    throw new Error(`corrupt persisted JSON at ${path}: malformed JSON`, { cause: error });
+  }
+  const parsed = schema.safeParse(value);
+  if (!parsed.success) {
+    const issues = parsed.error.issues
+      .slice(0, 3)
+      .map(
+        (issue) => `${issue.path.length > 0 ? issue.path.join(".") : "<root>"}: ${issue.message}`,
+      )
+      .join("; ");
+    throw new Error(`corrupt persisted JSON at ${path}: ${issues}`, { cause: parsed.error });
+  }
+  return parsed.data;
+};
+
+export const safeReadJson = async <S extends z.ZodType>(
+  path: string,
+  schema: S,
+): Promise<z.infer<S> | null> => {
+  let contents: string;
+  try {
+    contents = await readFile(path, "utf-8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw new Error(`failed to read persisted JSON at ${path}: ${errorMessage(error)}`, {
+      cause: error,
+    });
+  }
+  return parsePersistedJson(path, contents, schema);
+};
+
+/** Every regular file under `root` as a sorted list of relative paths. */
+export const walkFiles = async (root: string, maxFiles?: number): Promise<string[]> => {
+  if (!existsSync(root)) return [];
+  const out: string[] = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (!dir) continue;
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile()) {
+        out.push(relative(root, full));
+        if (maxFiles !== undefined && out.length > maxFiles) {
+          throw new Error(`file tree exceeds ${maxFiles} files: ${root}`);
+        }
+      }
+    }
+  }
+  return out.sort();
+};
+
+/**
+ * Walk authored trees without silently following or omitting a symlink that
+ * can change outside the experiment identity. Exact ignored paths support
+ * generated state directories whose names are project-configurable.
+ */
+export const walkAuthoredFiles = async (
+  root: string,
+  ignoredDirectoryNames: ReadonlySet<string> = new Set(),
+  ignoredPaths: ReadonlySet<string> = new Set(),
+): Promise<string[]> => {
+  if (!existsSync(root)) return [];
+  const out: string[] = [];
+  const stack = [root];
+  while (stack.length > 0) {
+    const dir = stack.pop();
+    if (!dir) continue;
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const full = join(dir, entry.name);
+      if (ignoredPaths.has(resolve(full))) continue;
+      if (entry.isDirectory() && ignoredDirectoryNames.has(entry.name)) continue;
+      if (entry.isSymbolicLink()) {
+        throw new Error(
+          `authored evaluation trees cannot contain symlinks: ${relative(root, full)}`,
+        );
+      }
+      if (entry.isDirectory()) stack.push(full);
+      else if (entry.isFile()) out.push(relative(root, full));
+    }
+  }
+  return out.sort();
+};