@dev.fast/whiteboard 0.0.0-stage → 0.2.1-preview.20261005.98

package/src/server/structural-comparisons.ts

@@ -0,0 +1,153 @@
+import type { StructuralDiffEvent } from "@dev.fast/review-protocol";
+
+import {
+  type StructuralDiffRequest,
+  structuralDiff,
+} from "./structural-diff.js";
+
+const IDLE_COMPARISONS = 10;
+
+/** Replays a pinned comparison to concurrent rendering and coverage consumers. */
+export class StructuralComparisons {
+  private readonly entries = new Map<string, Comparison>();
+
+  async *stream(
+    input: StructuralDiffRequest,
+  ): AsyncGenerator<StructuralDiffEvent> {
+    input.signal.throwIfAborted();
+
+    const key = JSON.stringify([
+      configGeneration,
+      input.repositoryPath,
+      input.comparison,
+      input.paths,
+    ]);
+
+    let entry = this.entries.get(key);
+
+    if (entry) this.entries.delete(key);
+    else entry = new Comparison(input);
+    this.entries.set(key, entry);
+
+    entry.readers++;
+
+    try {
+      yield* entry.read(input.signal);
+    } finally {
+      entry.readers--;
+
+      if (
+        (!entry.done && !entry.initialReady && !entry.readers) ||
+        entry.error ||
+        entry.failed
+      ) {
+        entry.abort.abort();
+        this.entries.delete(key);
+      }
+      // Keep the most recently read idle comparisons, including background enrichment.
+      // Coverage can finish before an editor subscribes; it must not cancel summaries.
+
+      const idle = [...this.entries].filter(
+        ([, value]) => (value.done || value.initialReady) && !value.readers,
+      );
+
+      for (const [oldKey, old] of idle.slice(0, -IDLE_COMPARISONS)) {
+        old.abort.abort();
+        this.entries.delete(oldKey);
+      }
+    }
+  }
+
+  close(): void {
+    for (const entry of this.entries.values()) entry.abort.abort();
+    this.entries.clear();
+  }
+}
+
+let configGeneration = 0;
+
+export function invalidateStructuralComparisons(): void {
+  configGeneration++;
+}
+
+class Comparison {
+  readonly abort = new AbortController();
+  readonly events: StructuralDiffEvent[] = [];
+  readers = 0;
+  done = false;
+  error: unknown;
+  failed = false;
+  initialReady = false;
+  private remaining: Set<string> | undefined;
+  private readonly listeners = new Set<() => void>();
+
+  constructor(input: StructuralDiffRequest) {
+    void this.run(input);
+  }
+
+  private async run(input: StructuralDiffRequest): Promise<void> {
+    try {
+      for await (const event of structuralDiff({
+        ...input,
+        signal: this.abort.signal,
+      })) {
+        if (event.type === "start") {
+          this.remaining = new Set(
+            event.files.map(
+              (entry) => (entry.file.rhs ?? entry.file.lhs)!.path,
+            ),
+          );
+          this.initialReady = this.remaining.size === 0;
+        } else if (event.type === "file") {
+          const path = (event.file.rhs ?? event.file.lhs)!.path;
+
+          if (!this.remaining?.delete(path))
+            throw new Error(`Unexpected structural result: ${path}`);
+          this.initialReady = this.remaining.size === 0;
+        }
+
+        if (event.type === "complete")
+          this.failed = event.failed > 0 || !!event.aborted;
+        this.events.push(event);
+
+        for (const wake of this.listeners) wake();
+      }
+    } catch (error) {
+      this.error = error;
+    } finally {
+      this.done = true;
+
+      for (const wake of this.listeners) wake();
+    }
+  }
+
+  async *read(signal: AbortSignal): AsyncGenerator<StructuralDiffEvent> {
+    let index = 0;
+
+    while (true) {
+      signal.throwIfAborted();
+
+      if (index < this.events.length) {
+        yield this.events[index++];
+        continue;
+      }
+
+      if (this.done) {
+        if (this.error) throw this.error;
+
+        return;
+      }
+
+      await new Promise<void>((resolve) => {
+        const wake = () => {
+          this.listeners.delete(wake);
+          signal.removeEventListener("abort", wake);
+          resolve();
+        };
+
+        this.listeners.add(wake);
+        signal.addEventListener("abort", wake, { once: true });
+      });
+    }
+  }
+}

package/src/server/structural-diff.ts

@@ -0,0 +1,186 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { createInterface } from "node:readline";
+
+import {
+  STRUCTURAL_DIFF_WIRE_VERSION,
+  type StructuralDiffEvent,
+  type StructuralProblem,
+  decodeStructuralDiffEvent,
+} from "@dev.fast/review-protocol";
+import { findReviewPackageRoot } from "@review/package-paths";
+
+import { installedFullDiffr } from "./diffr-languages.js";
+
+export type DiffComparison =
+  | { kind: "trees"; base: string; head: string }
+  | { kind: "merge-base"; base: string; head: string }
+  // The revision separates cached streams after a working-file save.
+  | { kind: "worktree"; base: string; revision: string };
+
+export interface StructuralDiffRequest {
+  repositoryPath: string;
+  comparison: DiffComparison;
+  paths?: readonly string[];
+  signal: AbortSignal;
+}
+
+export function diffrExecutable(
+  packageRoot = findReviewPackageRoot(import.meta.url),
+): string {
+  if (process.env.REVIEW_DIFFR_BINARY) return process.env.REVIEW_DIFFR_BINARY;
+
+  const full = installedFullDiffr(packageRoot);
+
+  if (full) return full;
+
+  const bundled = path.join(
+    packageRoot,
+    "bin",
+    process.platform === "win32" ? "diffr.exe" : "diffr",
+  );
+
+  return existsSync(bundled) ? bundled : "diffr";
+}
+
+export function diffrMissingError(): Error {
+  return new Error(
+    `Cannot find diffr at ${diffrExecutable()}. Whiteboard Desktop bundles it at bin/diffr under its runtime; in a checkout, run \`pnpm --filter @dev.fast/whiteboard ensure:diffr\` or install diffr on PATH, or set REVIEW_DIFFR_BINARY to its executable.`,
+  );
+}
+
+/**
+ * Stream validated diffr records. File errors and aborted completion are data;
+ * launch failures, malformed/truncated streams and unexpected exits throw.
+ * Closing the iterator (including a consumer's break) terminates the child.
+ */
+export async function* structuralDiff(
+  input: StructuralDiffRequest,
+): AsyncGenerator<StructuralDiffEvent> {
+  input.signal.throwIfAborted();
+  const comparison = input.comparison;
+
+  const args = [
+    "--repo",
+    input.repositoryPath,
+    "--format",
+    "ndjson",
+    "--stream-annotations",
+  ];
+
+  switch (comparison.kind) {
+    case "worktree":
+      args.push(comparison.base);
+      break;
+    case "trees":
+      args.push(comparison.base, comparison.head);
+      break;
+    case "merge-base":
+      args.push(`${comparison.base}...${comparison.head}`);
+  }
+
+  args.push("--", ...(input.paths ?? []));
+
+  const idleAbort = new AbortController();
+  const idle = setTimeout(() => idleAbort.abort(), 120_000);
+  const signal = AbortSignal.any([idleAbort.signal, input.signal]);
+
+  // The host inherits its own environment and runs from the repository, so
+  // diffr reads the user's config and keys exactly as it would from a shell.
+  console.info(
+    `[Review] structural diff: ${diffrExecutable()} ${args.join(" ")}`,
+  );
+
+  const child = spawn(diffrExecutable(), args, {
+    cwd: input.repositoryPath,
+    stdio: ["ignore", "pipe", "pipe"],
+    signal,
+  });
+
+  let stderr = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk: string) => {
+    stderr = (stderr + chunk).slice(-16_384);
+  });
+
+  const exited = new Promise<number | null>((resolve, reject) => {
+    child.once("error", (error: NodeJS.ErrnoException) => {
+      reject(error.code === "ENOENT" ? diffrMissingError() : error);
+    });
+    child.once("close", (code) => resolve(code));
+  });
+
+  const exitError = (code: number | null) =>
+    new Error(`diffr exited with ${code}: ${stderr}`);
+
+  // Observe process errors immediately, including before stdout closes.
+  void exited.catch(() => {});
+  let started = false;
+  let completed = false;
+  let aborted: StructuralProblem | undefined;
+  let failed = 0;
+  let annotationFailed = false;
+  const lines = createInterface({ input: child.stdout, crlfDelay: Infinity });
+
+  try {
+    for await (const line of lines) {
+      // Large comparisons may take minutes while continuing to make progress.
+      idle.refresh();
+
+      // Bound individual records, not the entire streamed comparison: a
+      // directory move can legitimately contain thousands of small files.
+      if (Buffer.byteLength(line) > 64 * 1024 * 1024)
+        throw new Error("Structural diff record exceeded 64 MiB.");
+
+      if (!line.trim()) continue;
+      const event = decodeStructuralDiffEvent(line);
+
+      if (completed) throw new Error("diffr emitted data after completion.");
+
+      if (!started) {
+        if (
+          event.type !== "start" ||
+          event.version !== STRUCTURAL_DIFF_WIRE_VERSION
+        ) {
+          throw new Error("Unsupported diffr stream protocol.");
+        }
+
+        started = true;
+      } else if (event.type === "complete") {
+        completed = true;
+
+        failed = event.failed;
+        aborted = event.aborted;
+      } else if (event.type === "annotations") {
+        annotationFailed ||= event.error !== undefined;
+      } else if (event.type !== "file") {
+        throw new Error(`Unexpected diffr event: ${event.type}`);
+      }
+
+      yield event;
+    }
+
+    if (!completed) {
+      const code = await exited;
+
+      if (code !== 0) throw exitError(code);
+      throw new Error("diffr stream ended before completion.");
+    }
+
+    // diffr exits 2 for file or enrichment failures already reported by the stream.
+    const code = await exited;
+
+    if (
+      code !== 0 &&
+      !(code === 2 && (failed > 0 || annotationFailed || aborted !== undefined))
+    )
+      throw exitError(code);
+  } finally {
+    clearTimeout(idle);
+    lines.close();
+
+    if (child.exitCode === null) child.kill();
+    await exited.catch(() => {});
+  }
+}

package/src/server/tutorial-service.ts

@@ -0,0 +1,241 @@
+import { createHash, randomUUID } from "node:crypto";
+import { cp, mkdir, readFile, rename, rm } from "node:fs/promises";
+import path from "node:path";
+
+import { resolveRevision } from "@dev.fast/local-vcs";
+import { writePrivateJsonAtomic } from "@dev.fast/trace-core";
+import {
+  documentSchema,
+  resourceReferences,
+} from "@review/review-api/document";
+import type { LocalReviewData } from "@review/review-api/local-data";
+import type { ReviewStore, Snapshot } from "@review/review-api/store";
+import { devReviewHome } from "@review/review-home-paths";
+import { z } from "zod";
+
+const authoredSchema = z.strictObject({
+  title: z.string().min(1),
+  document: documentSchema,
+});
+
+const pinsSchema = z.strictObject({
+  base: z.string().regex(/^[a-f0-9]{40}$/),
+  head: z.string().regex(/^[a-f0-9]{40}$/),
+});
+
+const stampSchema = z.object({
+  version: z.literal(10),
+  reviewUuid: z.string(),
+  contentHash: z.string(),
+});
+
+export async function readTutorialAssets(assetsRoot: string) {
+  const names = [
+    "document.json",
+    "trace.json",
+    "software-map.json",
+    "pins.json",
+  ];
+
+  const bytes = await Promise.all(
+    names.map((name) => readFile(path.join(assetsRoot, name), "utf8")),
+  );
+
+  return {
+    authored: authoredSchema.parse(JSON.parse(bytes[0]!)),
+    trace: JSON.parse(bytes[1]!),
+    model: JSON.parse(bytes[2]!),
+    pins: pinsSchema.parse(JSON.parse(bytes[3]!)),
+    contentHash: createHash("sha256")
+      .update(JSON.stringify(bytes))
+      .digest("hex"),
+  };
+}
+
+/** Create the shipped document through the same strict validation as authored reviews. */
+export async function createNativeTutorial(input: {
+  assetsRoot: string;
+  sampleRoot: string;
+  store: ReviewStore;
+  data: LocalReviewData;
+}) {
+  const assets = await readTutorialAssets(input.assetsRoot);
+  const repository = await input.data.register(input.sampleRoot);
+
+  const pins = await input.data.resolvePins(
+    repository.id,
+    assets.pins.base,
+    assets.pins.head,
+  );
+
+  const aliases = new Map<string, string>();
+  const traceId = randomUUID();
+  await input.data.upload({
+    id: traceId,
+    repositoryId: repository.id,
+    kind: "trace",
+    trace: assets.trace,
+  });
+  aliases.set("tutorial-trace", traceId);
+
+  for (const side of ["base", "head"] as const) {
+    const id = randomUUID();
+    await input.data.upload({
+      id,
+      repositoryId: repository.id,
+      kind: "map",
+      pins,
+      side,
+      model: assets.model,
+    });
+    aliases.set(`tutorial-map-${side}`, id);
+  }
+
+  for (const block of resourceReferences(assets.authored.document)) {
+    if (block.type === "trace_quote")
+      block.traceId = aliases.get(block.traceId) ?? block.traceId;
+
+    if (block.type === "software_map")
+      block.mapVersionId =
+        aliases.get(block.mapVersionId) ?? block.mapVersionId;
+  }
+
+  const result = await input.store.execute(
+    {
+      operation: {
+        type: "create",
+        title: assets.authored.title,
+        target: { kind: "commits", ...pins },
+      },
+    },
+    { document: assets.authored.document, origin: { tutorial: true } },
+  );
+
+  return {
+    snapshot: input.store.read(result.reviewId),
+    contentHash: assets.contentHash,
+  };
+}
+
+export function createTutorialService(input: {
+  packageRoot: string;
+  store: ReviewStore;
+  data: LocalReviewData;
+}) {
+  const tutorialRoot = path.join(devReviewHome(), "tutorial");
+  const sampleRoot = path.join(tutorialRoot, "sample-service");
+  const stampPath = path.join(tutorialRoot, "stamp.json");
+  const assetsRoot = path.join(input.packageRoot, "tutorial");
+
+  const readStamp = async () =>
+    stampSchema.safeParse(
+      await readFile(stampPath, "utf8")
+        .then((value) => JSON.parse(value))
+        .catch(() => null),
+    ).data;
+
+  async function find(): Promise<Snapshot | null> {
+    try {
+      const stamp = await readStamp();
+
+      if (!stamp || !input.store.has(stamp.reviewUuid)) return null;
+      const snapshot = input.store.read(stamp.reviewUuid);
+      const assets = await readTutorialAssets(assetsRoot);
+
+      const [head, base] = await Promise.all([
+        resolveRevision(sampleRoot, "HEAD"),
+        resolveRevision(sampleRoot, "HEAD^"),
+      ]);
+
+      return snapshot.origin?.tutorial &&
+        stamp.contentHash === assets.contentHash &&
+        head &&
+        base &&
+        snapshot.pins?.head === head.commit &&
+        snapshot.pins?.base === base.commit &&
+        head.commit === assets.pins.head &&
+        base.commit === assets.pins.base
+        ? snapshot
+        : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async function cleanup() {
+    for (const reviewId of input.store.tutorialIds())
+      await input.store.execute({
+        operation: { type: "delete", reviewId },
+      });
+
+    // Windows cannot delete a checkout while its Git reader or watchers
+    // hold it open, and handles can outlive their close briefly.
+    for (const repository of input.store.repositories()) {
+      const relative = path.relative(tutorialRoot, repository.path);
+
+      if (relative && !relative.startsWith("..") && !path.isAbsolute(relative))
+        await input.data.forgetRepository(repository.id);
+    }
+
+    await rm(tutorialRoot, { recursive: true, force: true, maxRetries: 10 });
+  }
+
+  return {
+    async status() {
+      return {
+        version: 1 as const,
+        reviewUuid: (await find())?.reviewId ?? null,
+      };
+    },
+    async referencesReview(id: string) {
+      return (
+        input.store.has(id) && input.store.read(id).origin?.tutorial === true
+      );
+    },
+    async prepare(options?: { beforeReset(): Promise<void> }) {
+      const current = await find();
+
+      if (current) return current;
+
+      await readTutorialAssets(assetsRoot);
+      await options?.beforeReset();
+      await cleanup();
+      await mkdir(tutorialRoot, { recursive: true, mode: 0o700 });
+
+      const temporaryRoot = path.join(
+        tutorialRoot,
+        `.sample-service-${randomUUID()}`,
+      );
+
+      try {
+        await cp(path.join(assetsRoot, "sample-service"), temporaryRoot, {
+          recursive: true,
+        });
+        await cp(
+          path.join(assetsRoot, "git-stub"),
+          path.join(temporaryRoot, ".git"),
+          { recursive: true },
+        );
+        await rename(temporaryRoot, sampleRoot);
+
+        const { snapshot, contentHash } = await createNativeTutorial({
+          assetsRoot,
+          sampleRoot,
+          store: input.store,
+          data: input.data,
+        });
+
+        await writePrivateJsonAtomic(stampPath, {
+          version: 10,
+          reviewUuid: snapshot.reviewId,
+          contentHash,
+        });
+
+        return snapshot;
+      } finally {
+        await rm(temporaryRoot, { recursive: true, force: true });
+      }
+    },
+    cleanup,
+  };
+}