@bjoernrochel/sevro 0.1.0-rc.2 → 0.1.0-rc.21

package/src/fixtures/generated.ts

@@ -0,0 +1,300 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { canonicalJson } from "../identity";
+import { prepareFixtureBin } from "./bin";
+import { prepareGitHooks } from "./git-hooks";
+import { fixtureParts } from "./preparation";
+
+const MAX_COMMITS = 128;
+const MAX_FILES = 1024;
+const MAX_BYTES = 32 * 1024 * 1024;
+const MAX_GIT_OUTPUT = 64 * 1024;
+
+export interface GeneratedFixture {
+  kind: "generated";
+  commits: { message: string; files: Record<string, string> }[];
+  files?: Record<string, string>;
+  staged?: string[];
+  commitFiles?: boolean;
+  hooks?: Record<string, string>;
+  bin?: Record<string, string>;
+}
+
+function validFiles(value: unknown): value is Record<string, string> {
+  return (
+    Boolean(value && typeof value === "object" && !Array.isArray(value)) &&
+    Object.values(value as object).every((item) => typeof item === "string")
+  );
+}
+
+function validPath(path: string): void {
+  const parts = fixtureParts(path);
+  if (parts.some((part) => part.toLowerCase() === ".git"))
+    throw new Error("generated fixture cannot write repository metadata");
+}
+
+interface FixtureContents {
+  bytes: number;
+  files: number;
+  paths: string[];
+}
+
+function fixtureRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("invalid generated fixture");
+  return value as Record<string, unknown>;
+}
+
+function fixtureKeys(fixture: Record<string, unknown>): void {
+  const keys = [
+    "kind",
+    "commits",
+    "files",
+    "staged",
+    "commitFiles",
+    "hooks",
+    "bin",
+  ];
+  if (
+    fixture.kind !== "generated" ||
+    Object.keys(fixture).some((key) => !keys.includes(key))
+  )
+    throw new Error("invalid generated fixture");
+}
+
+function stringArray(value: unknown): value is string[] {
+  return (
+    Array.isArray(value) &&
+    value.every((item: unknown) => typeof item === "string")
+  );
+}
+
+function fixtureOptionalFields(fixture: Record<string, unknown>): void {
+  if (fixture.files !== undefined && !validFiles(fixture.files))
+    throw new Error("invalid generated fixture");
+  validateStagedField(fixture.staged);
+  if (
+    fixture.commitFiles !== undefined &&
+    typeof fixture.commitFiles !== "boolean"
+  )
+    throw new Error("invalid generated fixture");
+}
+
+function validateStagedField(value: unknown): void {
+  if (value !== undefined && !stringArray(value))
+    throw new Error("invalid generated fixture");
+}
+
+function fixtureCommits(value: unknown): unknown[] {
+  if (!Array.isArray(value) || value.length > MAX_COMMITS)
+    throw new Error("invalid generated fixture");
+  return value;
+}
+
+function commitMessage(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    Boolean(value.trim()) &&
+    Buffer.byteLength(value, "utf8") <= 4096
+  );
+}
+
+function commitRecord(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("invalid generated fixture commit");
+  return value as Record<string, unknown>;
+}
+
+function prepareCommit(value: unknown): GeneratedFixture["commits"][number] {
+  const commit = commitRecord(value);
+  if (
+    Object.keys(commit).some((key) => key !== "message" && key !== "files") ||
+    !commitMessage(commit.message)
+  )
+    throw new Error("invalid generated fixture commit");
+  if (!validFiles(commit.files) || Object.keys(commit.files).length === 0)
+    throw new Error("invalid generated fixture commit");
+  return { message: commit.message, files: commit.files };
+}
+
+function countFiles(
+  contents: FixtureContents,
+  files: Record<string, string>,
+): void {
+  for (const [path, content] of Object.entries(files)) {
+    validPath(path);
+    contents.paths.push(path);
+    contents.files++;
+    contents.bytes +=
+      Buffer.byteLength(path, "utf8") + Buffer.byteLength(content, "utf8");
+  }
+}
+
+function validateContents(contents: FixtureContents): void {
+  if (contents.files > MAX_FILES || contents.bytes > MAX_BYTES)
+    throw new Error("generated fixture exceeds the size limit");
+  const normalized = [...new Set(contents.paths)].map((path) =>
+    path.toLowerCase(),
+  );
+  for (const [index, path] of normalized.entries()) {
+    if (normalized.slice(0, index).some((other) => pathsCollide(path, other)))
+      throw new Error("generated fixture paths collide");
+  }
+}
+
+function pathsCollide(path: string, other: string): boolean {
+  return (
+    path === other ||
+    path.startsWith(`${other}/`) ||
+    other.startsWith(`${path}/`)
+  );
+}
+
+function validateStaging(
+  staged: string[],
+  overlay: Record<string, string>,
+  commitFiles: unknown,
+): void {
+  if (
+    new Set(staged.map((path) => path.toLowerCase())).size !== staged.length ||
+    staged.some((path) => !Object.hasOwn(overlay, path)) ||
+    emptyOverlayCommit(commitFiles, overlay)
+  )
+    throw new Error("invalid generated fixture staging");
+}
+
+function emptyOverlayCommit(
+  commitFiles: unknown,
+  overlay: Record<string, string>,
+): boolean {
+  return commitFiles === true && Object.keys(overlay).length === 0;
+}
+
+/** Freeze a bounded declarative history before any host or fixture work. */
+export function prepareGeneratedFixture(value: unknown): GeneratedFixture {
+  const fixture = fixtureRecord(value);
+  fixtureKeys(fixture);
+  const commits = fixtureCommits(fixture.commits);
+  fixtureOptionalFields(fixture);
+  prepareGitHooks(fixture.hooks);
+  prepareFixtureBin(fixture.bin);
+  const contents: FixtureContents = { bytes: 0, files: 0, paths: [] };
+  for (const value of commits) {
+    const commit = prepareCommit(value);
+    contents.bytes += Buffer.byteLength(commit.message, "utf8");
+    countFiles(contents, commit.files);
+  }
+  // The optional fields were checked above; preserve absent fields in the frozen declaration.
+  const overlay = validFiles(fixture.files) ? fixture.files : {};
+  const staged = stringArray(fixture.staged) ? fixture.staged : [];
+  countFiles(contents, overlay);
+  contents.bytes += staged.reduce(
+    (size, path) => size + Buffer.byteLength(path, "utf8"),
+    0,
+  );
+  validateContents(contents);
+  validateStaging(staged, overlay, fixture.commitFiles);
+  return JSON.parse(canonicalJson(fixture)) as GeneratedFixture;
+}
+
+function gitEnvironment() {
+  const nullDevice = process.platform === "win32" ? "NUL" : "/dev/null";
+  return {
+    PATH: process.env.PATH ?? "/usr/bin:/bin",
+    ...(process.env.SystemRoot ? { SystemRoot: process.env.SystemRoot } : {}),
+    GIT_CONFIG_NOSYSTEM: "1",
+    GIT_CONFIG_GLOBAL: nullDevice,
+    GIT_TERMINAL_PROMPT: "0",
+    GIT_AUTHOR_NAME: "Sevro Fixture",
+    GIT_AUTHOR_EMAIL: "fixture@sevro.invalid",
+    GIT_COMMITTER_NAME: "Sevro Fixture",
+    GIT_COMMITTER_EMAIL: "fixture@sevro.invalid",
+    GIT_AUTHOR_DATE: "2000-01-01T00:00:00+00:00",
+    GIT_COMMITTER_DATE: "2000-01-01T00:00:00+00:00",
+  };
+}
+
+async function git(workspace: string, args: string[]): Promise<void> {
+  async function bounded(stream: ReadableStream<Uint8Array>): Promise<void> {
+    let size = 0;
+    for await (const chunk of stream) {
+      size += chunk.byteLength;
+      if (size > MAX_GIT_OUTPUT)
+        throw new Error("generated fixture Git output is too large");
+    }
+  }
+  const proc = Bun.spawn(
+    [
+      "git",
+      "-c",
+      `core.hooksPath=${process.platform === "win32" ? "NUL" : "/dev/null"}`,
+      ...args,
+    ],
+    {
+      cwd: workspace,
+      stdout: "pipe",
+      stderr: "pipe",
+      env: gitEnvironment(),
+    },
+  );
+  try {
+    const [, , code] = await Promise.all([
+      bounded(proc.stdout),
+      bounded(proc.stderr),
+      proc.exited,
+    ]);
+    if (code !== 0) throw new Error();
+  } catch (cause) {
+    try {
+      proc.kill("SIGKILL");
+    } catch {
+      // The process may have exited before the failure was observed.
+    }
+    await proc.exited;
+    throw new Error("generated fixture Git operation failed", { cause });
+  }
+}
+
+async function writeFiles(
+  workspace: string,
+  files: Record<string, string>,
+): Promise<void> {
+  for (const [path, content] of Object.entries(files)) {
+    const target = join(workspace, ...fixtureParts(path));
+    await mkdir(dirname(target), { recursive: true, mode: 0o700 });
+    await writeFile(target, content, { flag: "w", mode: 0o600 });
+  }
+}
+
+/** Build a deterministic local Git history, then apply working-tree state. */
+export async function materializeGeneratedFixture(
+  fixture: GeneratedFixture,
+  workspace: string,
+): Promise<void> {
+  await git(workspace, ["init", "--quiet", "--initial-branch=main"]);
+  for (const commit of fixture.commits) {
+    await writeFiles(workspace, commit.files);
+    await git(workspace, ["add", "--", ...Object.keys(commit.files)]);
+    await git(workspace, ["commit", "--quiet", "-m", commit.message]);
+  }
+  await applyGeneratedOverlay(fixture, workspace);
+}
+
+async function applyGeneratedOverlay(
+  fixture: GeneratedFixture,
+  workspace: string,
+): Promise<void> {
+  const overlay = fixture.files ?? {};
+  await writeFiles(workspace, overlay);
+  if (fixture.commitFiles) {
+    await git(workspace, ["add", "--", ...Object.keys(overlay)]);
+    await git(workspace, [
+      "commit",
+      "--quiet",
+      "-m",
+      "Add evaluation scaffolding",
+    ]);
+  }
+  if (fixture.staged?.length)
+    await git(workspace, ["add", "--", ...fixture.staged]);
+}

package/src/fixtures/git-hooks.ts

@@ -0,0 +1,24 @@
+import { join } from "node:path";
+import { prepareFixtureTools, installFixtureTools } from "./tools";
+
+/** Bound hook declarations and keep every name inside Git's hooks directory. */
+export function prepareGitHooks(value: unknown): Record<string, string> | null {
+  return prepareFixtureTools(
+    value,
+    /^[a-z][a-z0-9-]*$/,
+    32,
+    "invalid fixture hooks",
+  );
+}
+
+/** Install executable hooks only after fixture commits and overlays are ready. */
+export async function installGitHooks(
+  hooks: Record<string, string> | undefined,
+  workspace: string,
+): Promise<void> {
+  if (!hooks) return;
+  await installFixtureTools(hooks, join(workspace, ".git", "hooks"), {
+    directory: "fixture Git hooks directory is invalid",
+    target: "fixture Git hook target is invalid",
+  });
+}

package/src/fixtures/preparation.ts

@@ -0,0 +1,270 @@
+import { isMissingFile } from "./tools";
+import { sha256 } from "../identity";
+import { lstat, mkdir, readFile, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MAX_ARTIFACT_BYTES = 8 * 1024 * 1024;
+const MAX_TOTAL_BYTES = 32 * 1024 * 1024;
+
+export interface PreparationArtifact {
+  id: string;
+  relativePath: string;
+  sha256: string;
+  contentBase64?: string;
+  sourceRef?: string;
+  gitExclude?: boolean;
+  executable?: boolean;
+}
+
+export interface InlineArtifact {
+  id: string;
+  relativePath: string;
+  sha256: string;
+  bytes: Uint8Array;
+  gitExclude?: boolean;
+  executable?: boolean;
+}
+
+export interface PreparationSources {
+  root: string;
+  refs: Record<string, string>;
+}
+
+export function fixtureParts(relativePath: string): string[] {
+  if (!validFixturePath(relativePath))
+    throw new Error(`invalid fixture path: ${relativePath}`);
+  const parts = relativePath.split("/");
+  if (parts.some((part) => !part || part === "." || part === ".."))
+    throw new Error(`invalid fixture path: ${relativePath}`);
+  return parts;
+}
+
+function validFixturePath(path: string): boolean {
+  return !!path && !isAbsolute(path) && !path.includes("\\") && !/:/.test(path);
+}
+
+/** Refuse fixture or setup-created links before mounting trusted artifact bytes. */
+export async function safePreparationTarget(
+  workspace: string,
+  relativePath: string,
+): Promise<string> {
+  const parts = fixtureParts(relativePath);
+  let parent = workspace;
+  for (const part of parts.slice(0, -1)) {
+    parent = join(parent, part);
+    await preparationParent(parent);
+  }
+  const target = join(workspace, ...parts);
+  await requireUnusedPreparationTarget(target);
+  return target;
+}
+
+async function preparationParent(path: string): Promise<void> {
+  try {
+    const entry = await lstat(path);
+    if (!entry.isDirectory() || entry.isSymbolicLink())
+      throw new Error("preparation artifact traverses a non-directory");
+  } catch (error) {
+    if (!isMissingFile(error)) throw error;
+    await mkdir(path, { mode: 0o700 });
+  }
+}
+async function requireUnusedPreparationTarget(path: string): Promise<void> {
+  try {
+    await lstat(path);
+    throw new Error("preparation artifact path already exists");
+  } catch (error) {
+    if (!isMissingFile(error)) throw error;
+  }
+}
+function collidingPaths(left: string, right: string): boolean {
+  return (
+    left === right ||
+    left.startsWith(`${right}/`) ||
+    right.startsWith(`${left}/`)
+  );
+}
+
+function validatePaths(paths: string[]): void {
+  const normalized = paths.map((path) =>
+    fixtureParts(path).join("/").toLowerCase(),
+  );
+  for (const [index, path] of normalized.entries())
+    for (const other of normalized.slice(0, index))
+      if (collidingPaths(path, other)) throw new Error("fixture paths collide");
+}
+
+/** Decode declared inline artifacts before creating a candidate workspace. */
+export function prepareInlineArtifacts(
+  declarations: PreparationArtifact[],
+  fixturePaths: string[],
+): InlineArtifact[] {
+  validatePaths([
+    ...fixturePaths,
+    ...declarations.map((item) => item.relativePath),
+  ]);
+  const state = { ids: new Set<string>(), bytes: 0 };
+  return declarations.map((item) => inlineArtifact(item, state));
+}
+
+function requireArtifactFlags(item: PreparationArtifact): void {
+  if (item.gitExclude !== undefined && typeof item.gitExclude !== "boolean")
+    throw new Error("preparation artifact gitExclude must be boolean");
+  if (item.executable !== undefined && typeof item.executable !== "boolean")
+    throw new Error("preparation artifact executable must be boolean");
+}
+function containsControlCharacter(path: string): boolean {
+  return Array.from(path).some(
+    (character) =>
+      character.charCodeAt(0) < 0x20 || character.charCodeAt(0) === 0x7f,
+  );
+}
+function requireInlineSource(
+  item: PreparationArtifact,
+): asserts item is PreparationArtifact & { contentBase64: string } {
+  if (item.gitExclude && containsControlCharacter(item.relativePath))
+    throw new Error("Git-excluded artifact path contains control characters");
+  if (item.sourceRef !== undefined || typeof item.contentBase64 !== "string")
+    throw new Error("preparation source references are not supported");
+}
+function canonicalBase64Bytes(encoded: string): Buffer {
+  if (
+    !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(
+      encoded,
+    )
+  )
+    throw new Error("preparation artifact content is not canonical base64");
+  const bytes = Buffer.from(encoded, "base64");
+  if (bytes.toString("base64") !== encoded)
+    throw new Error("preparation artifact content is not canonical base64");
+  return bytes;
+}
+function requireArtifactSize(bytes: number, total: number): void {
+  if (bytes > MAX_ARTIFACT_BYTES || total > MAX_TOTAL_BYTES)
+    throw new Error("preparation artifacts exceed the size limit");
+}
+function artifactFlags(item: PreparationArtifact) {
+  return {
+    ...(item.gitExclude === undefined ? {} : { gitExclude: item.gitExclude }),
+    ...(item.executable === undefined ? {} : { executable: item.executable }),
+  };
+}
+function inlineArtifact(
+  item: PreparationArtifact,
+  state: { ids: Set<string>; bytes: number },
+): InlineArtifact {
+  if (!item.id || state.ids.has(item.id))
+    throw new Error("preparation artifact IDs must be unique and nonempty");
+  state.ids.add(item.id);
+  requireArtifactFlags(item);
+  requireInlineSource(item);
+  const bytes = canonicalBase64Bytes(item.contentBase64);
+  state.bytes += bytes.byteLength;
+  requireArtifactSize(bytes.byteLength, state.bytes);
+  if (sha256(bytes) !== item.sha256)
+    throw new Error("preparation artifact digest does not match content");
+  return {
+    id: item.id,
+    relativePath: item.relativePath,
+    sha256: item.sha256,
+    bytes,
+    ...artifactFlags(item),
+  };
+}
+
+/** Resolve opaque source IDs only through an explicitly declared case source map. */
+export async function prepareArtifacts(
+  declarations: PreparationArtifact[],
+  fixturePaths: string[],
+  sources?: PreparationSources,
+): Promise<InlineArtifact[]> {
+  if (!declarations.some((item) => item.sourceRef !== undefined))
+    return prepareInlineArtifacts(declarations, fixturePaths);
+  const context = await preparationSourceContext(sources);
+  const resolved: PreparationArtifact[] = [];
+  const state = { bytes: 0 };
+  for (const item of declarations)
+    resolved.push(await resolveSourceArtifact(item, context, state));
+  return prepareInlineArtifacts(resolved, fixturePaths);
+}
+
+async function preparationSourceContext(
+  sources: PreparationSources | undefined,
+) {
+  if (!sources || !isAbsolute(sources.root))
+    throw new Error("preparation source root is required and must be absolute");
+  const root = await realpath(sources.root).catch((cause: unknown) => {
+    throw new Error("preparation source root is unreadable", { cause });
+  });
+  return { root, refs: sources.refs };
+}
+function sourceArtifactUrl(
+  item: PreparationArtifact & { sourceRef: string },
+  refs: Record<string, string>,
+): string {
+  if (item.contentBase64 !== undefined)
+    throw new Error("preparation artifact has two content sources");
+  if (!Object.hasOwn(refs, item.sourceRef))
+    throw new Error("preparation source reference is not declared");
+  const url = refs[item.sourceRef];
+  if (typeof url !== "string" || !url.startsWith("file:///"))
+    throw new Error("preparation source reference must be a file URL");
+  return url;
+}
+async function preparationSourcePath(url: string): Promise<string> {
+  try {
+    return await realpath(fileURLToPath(url));
+  } catch (cause) {
+    throw new Error("preparation source is unreadable", { cause });
+  }
+}
+function requireContainedSource(root: string, path: string): void {
+  const child = relative(root, path);
+  if (
+    !child ||
+    child === ".." ||
+    child.startsWith(`..${sep}`) ||
+    isAbsolute(child)
+  )
+    throw new Error("preparation source escapes its declared root");
+}
+async function preparationSourceSize(path: string): Promise<number> {
+  try {
+    return (await stat(path)).size;
+  } catch (cause) {
+    throw new Error("preparation source is unreadable", { cause });
+  }
+}
+async function preparationSourceBytes(path: string): Promise<Buffer> {
+  try {
+    return await readFile(path);
+  } catch (cause) {
+    throw new Error("preparation source is unreadable", { cause });
+  }
+}
+async function resolveSourceArtifact(
+  item: PreparationArtifact,
+  context: Awaited<ReturnType<typeof preparationSourceContext>>,
+  state: { bytes: number },
+): Promise<PreparationArtifact> {
+  if (item.sourceRef === undefined) return item;
+  const url = sourceArtifactUrl(
+    { ...item, sourceRef: item.sourceRef },
+    context.refs,
+  );
+  const path = await preparationSourcePath(url);
+  requireContainedSource(context.root, path);
+  const size = await preparationSourceSize(path);
+  requireArtifactSize(size, state.bytes + size);
+  const bytes = await preparationSourceBytes(path);
+  state.bytes += bytes.byteLength;
+  requireArtifactSize(bytes.byteLength, state.bytes);
+  return {
+    id: item.id,
+    relativePath: item.relativePath,
+    sha256: item.sha256,
+    contentBase64: bytes.toString("base64"),
+    ...artifactFlags(item),
+  };
+}