@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/runtime.ts

@@ -0,0 +1,74 @@
+import { spawn } from "node:child_process";
+import path from "node:path";
+
+export async function resolveReviewRoot(
+  cwd: string,
+  execFile: typeof execFilePromise = execFilePromise,
+): Promise<string> {
+  const initialCwd = path.resolve(cwd);
+
+  try {
+    // cwd-based invocation: jj walks up from cwd like git does, while
+    // `-R <subdir>` fails for a subdirectory of a workspace and would
+    // silently fall back to git's cwd walk (the OUTER repo, for a
+    // non-colocated jj workspace nested in another git repo).
+    const { stdout } = await execFile("jj", ["root"], { cwd: initialCwd });
+    const root = stdout.trim();
+
+    if (root) return path.resolve(root);
+  } catch {
+    // Not a jj workspace, or jj is unavailable. Try Git below.
+  }
+
+  try {
+    const { stdout } = await execFile("git", [
+      "-C",
+      initialCwd,
+      "rev-parse",
+      "--show-toplevel",
+    ]);
+
+    const root = stdout.trim();
+
+    if (root) return path.resolve(root);
+  } catch {
+    // Non-VCS directories keep their original cwd for existing review behavior.
+  }
+
+  return initialCwd;
+}
+
+function execFilePromise(
+  file: string,
+  args: string[],
+  options: { cwd?: string } = {},
+): Promise<{ stdout: string }> {
+  return execFileUntraced(file, args, options);
+}
+
+function execFileUntraced(
+  file: string,
+  args: string[],
+  options: { cwd?: string } = {},
+): Promise<{ stdout: string }> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(file, args, {
+      cwd: options.cwd,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.on("data", (chunk) => {
+      stdout += String(chunk);
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += String(chunk);
+    });
+    child.on("error", reject);
+    child.on("exit", (code) => {
+      if (code === 0) resolve({ stdout });
+      else reject(new Error(stderr.trim() || `${file} exited with ${code}`));
+    });
+  });
+}

package/src/server/account-alias.ts

@@ -0,0 +1,30 @@
+import { StoreClient, readStoreAuth } from "@dev.fast/trace-core";
+import type { ReviewTelemetry } from "@review/review-telemetry";
+
+/**
+ * After a login, link this install to the signed-in account by a hash of its
+ * account id. Best effort and never throws: the login already succeeded.
+ */
+export async function aliasInstallationToAccount(
+  telemetry: Pick<ReviewTelemetry, "captureAccountAlias">,
+  env: NodeJS.ProcessEnv = process.env,
+  fetchImpl?: typeof fetch,
+): Promise<void> {
+  try {
+    const auth = await readStoreAuth(env);
+
+    if (!auth) return;
+
+    await telemetry.captureAccountAlias(async () => {
+      const session = await new StoreClient({
+        origin: auth.origin,
+        token: auth.token,
+        fetch: fetchImpl,
+      }).session();
+
+      return session.user.id;
+    });
+  } catch {
+    // No alias this time; the next login tries again.
+  }
+}

package/src/server/bounded-stream.ts

@@ -0,0 +1,34 @@
+export class StreamLimitError extends Error {
+  constructor() {
+    super("Stream exceeds its byte limit.");
+  }
+}
+
+export async function readBoundedStream(
+  stream: ReadableStream<Uint8Array>,
+  limit: number,
+): Promise<Buffer> {
+  const reader = stream.getReader();
+  const parts: Uint8Array[] = [];
+  let size = 0;
+
+  try {
+    for (;;) {
+      const { value, done } = await reader.read();
+
+      if (done) break;
+      size += value.byteLength;
+
+      if (size > limit) {
+        await reader.cancel().catch(() => {});
+        throw new StreamLimitError();
+      }
+
+      parts.push(value);
+    }
+
+    return Buffer.concat(parts, size);
+  } finally {
+    reader.releaseLock();
+  }
+}

package/src/server/bug-report.ts

@@ -0,0 +1,301 @@
+import { createHash } from "node:crypto";
+import { gzipSync } from "node:zlib";
+
+import { type JsonValue } from "@dev.fast/json";
+import {
+  type ReviewBugReportMetaV2,
+  type ReviewBugReportRequest,
+  parseReviewBugReportResponse,
+} from "@dev.fast/review-protocol";
+import { readReviewPackageVersion } from "@review/package-paths";
+import { type PostHogCaptureProperties } from "@review/posthog-capture-client";
+import { type ReviewDiffFilesResult } from "@review/review-diff-files";
+
+const BUG_REPORT_URL = "https://bug.dev.fast/api/v2/reports";
+
+const MAX_PAYLOAD_BYTES = 10 * 1024 * 1024;
+
+const UPSTREAM_TIMEOUT_MS = 20_000;
+
+type AttachmentName = "review" | "map" | "diff";
+
+type AttachmentError = {
+  attachment: AttachmentName;
+  error: "unavailable";
+};
+
+export interface BugReportPayload {
+  schema_version: 4;
+  description: string;
+  screenshot?: { mime: "image/jpeg"; base64: string };
+  // File name to text. The document alone cannot render: every anchor lives in
+  // a sibling TypeScript module.
+  review?: Record<string, string>;
+  map?: string;
+  diff?: ReviewDiffFilesResult;
+  diagnostics: {
+    app_version: string;
+    cli_version: string;
+    platform: NodeJS.Platform;
+    app_session_id: string;
+    client_error_names: string[];
+    attachment_errors?: AttachmentError[];
+    // Review source files the report did not send, by name. Triage reads a
+    // missing module as a rendering bug unless the report says it dropped one.
+    review_omitted_files?: string[];
+    /** The telemetry envelope, so triage can tell channel, environment and surface apart. */
+    telemetry?: Record<string, JsonValue>;
+  };
+}
+
+export class BugReportUpstreamError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "BugReportUpstreamError";
+  }
+}
+
+export interface BugReportSource {
+  review(): Promise<{ files: Record<string, string>; omitted: string[] }>;
+  map(): Promise<string | null>;
+  diff(): Promise<ReviewDiffFilesResult>;
+}
+
+export async function submitReviewBugReport(input: {
+  report: ReviewBugReportRequest;
+  clientErrorNames: string[];
+  fetchImpl?: typeof fetch;
+  source: BugReportSource;
+  telemetryEnvelope?: PostHogCaptureProperties;
+}) {
+  const cliVersion = readReviewPackageVersion();
+  const attachmentErrors: AttachmentError[] = [];
+
+  const payload: BugReportPayload = {
+    schema_version: 4,
+    description: input.report.description,
+    diagnostics: {
+      app_version: input.report.app_version,
+      cli_version: cliVersion,
+      platform: process.platform,
+      app_session_id: input.report.app_session_id,
+      client_error_names: input.clientErrorNames.slice(-20),
+    },
+  };
+
+  if (input.telemetryEnvelope) {
+    payload.diagnostics.telemetry = Object.fromEntries(
+      Object.entries(input.telemetryEnvelope).filter(
+        (entry): entry is [string, JsonValue] => entry[1] !== undefined,
+      ),
+    );
+  }
+
+  if (input.report.screenshot) payload.screenshot = input.report.screenshot;
+
+  let reviewSource: Record<string, string> | undefined;
+  let omittedReviewFiles: string[] | undefined;
+  let mapSource: string | undefined;
+  let changedFileDiffs: ReviewDiffFilesResult | undefined;
+  const tasks: Array<Promise<void>> = [];
+
+  if (input.report.include_review) {
+    tasks.push(
+      input.source.review().then(
+        (result) => {
+          reviewSource = result.files;
+
+          if (result.omitted.length > 0) omittedReviewFiles = result.omitted;
+        },
+        () => {
+          attachmentErrors.push(unavailable("review"));
+        },
+      ),
+    );
+  }
+
+  if (input.report.include_map) {
+    tasks.push(
+      input.source.map().then(
+        // A review does not need a software map: #840 split document and map
+        // publishing, so "no map" is a normal state, not a failed read.
+        // `readSoftwareMapSourceForRef` returns null when there is nothing to
+        // send and throws when a read fails, so only the throw is an error.
+        (source) => {
+          if (source !== null) mapSource = source;
+        },
+        () => {
+          attachmentErrors.push(unavailable("map"));
+        },
+      ),
+    );
+  }
+
+  if (input.report.include_diff) {
+    tasks.push(
+      input.source.diff().then(
+        (diff) => {
+          changedFileDiffs = diff;
+        },
+        () => {
+          attachmentErrors.push(unavailable("diff"));
+        },
+      ),
+    );
+  }
+
+  await Promise.all(tasks);
+
+  if (reviewSource !== undefined) payload.review = reviewSource;
+
+  if (omittedReviewFiles !== undefined) {
+    payload.diagnostics.review_omitted_files = omittedReviewFiles;
+  }
+
+  if (mapSource !== undefined) payload.map = mapSource;
+
+  if (changedFileDiffs !== undefined) payload.diff = changedFileDiffs;
+
+  if (attachmentErrors.length > 0) {
+    payload.diagnostics.attachment_errors = attachmentErrors.sort(byAttachment);
+  }
+
+  const response = await (input.fetchImpl ?? fetch)(BUG_REPORT_URL, {
+    method: "POST",
+    body: buildBugReportRequest(payload, {
+      appVersion: input.report.app_version,
+      cliVersion,
+    }),
+    signal: AbortSignal.timeout(UPSTREAM_TIMEOUT_MS),
+  }).catch((error) => {
+    throw new BugReportUpstreamError(
+      502,
+      error instanceof Error ? error.message : "Bug report service failed.",
+    );
+  });
+
+  const responseBody = await response.json().catch(() => null);
+
+  if (!response.ok) {
+    throw new BugReportUpstreamError(
+      response.status === 429 || response.status === 413
+        ? response.status
+        : 502,
+      response.status === 429
+        ? "Too many reports. Try again later."
+        : response.status === 413
+          ? "Bug report is too large."
+          : "Bug report service failed.",
+    );
+  }
+
+  const result = parseReviewBugReportResponse(responseBody);
+
+  if (!result.ok) throw new BugReportUpstreamError(502, result.error);
+
+  return result;
+}
+
+function buildBugReportRequest(
+  payload: BugReportPayload,
+  input: {
+    appVersion: string;
+    cliVersion: string;
+    maxPayloadBytes?: number;
+  },
+): FormData {
+  const maxPayloadBytes = input.maxPayloadBytes ?? MAX_PAYLOAD_BYTES;
+  let truncatedDiff = false;
+  let truncatedMap = false;
+  let truncatedScreenshot = false;
+  let payloadBytes = gzipPayload(payload);
+
+  if (payloadBytes.byteLength > maxPayloadBytes && payload.diff) {
+    delete payload.diff;
+    truncatedDiff = true;
+    payloadBytes = gzipPayload(payload);
+  }
+
+  if (payloadBytes.byteLength > maxPayloadBytes && payload.map) {
+    delete payload.map;
+    truncatedMap = true;
+    payloadBytes = gzipPayload(payload);
+  }
+
+  if (payloadBytes.byteLength > maxPayloadBytes && payload.screenshot) {
+    delete payload.screenshot;
+    truncatedScreenshot = true;
+    payloadBytes = gzipPayload(payload);
+  }
+
+  if (payloadBytes.byteLength > maxPayloadBytes && payload.review) {
+    delete payload.review;
+    payloadBytes = gzipPayload(payload);
+  }
+
+  if (payloadBytes.byteLength > maxPayloadBytes) {
+    throw new BugReportUpstreamError(413, "Bug report is too large.");
+  }
+
+  const meta: ReviewBugReportMetaV2 = {
+    schema_version: 2,
+    description_length: Buffer.byteLength(payload.description),
+    has_review: payload.review !== undefined,
+    has_map: payload.map !== undefined,
+    has_diff: payload.diff !== undefined,
+    has_screenshot: payload.screenshot !== undefined,
+    has_trace: false,
+    payload_bytes: payloadBytes.byteLength,
+    app_version: input.appVersion,
+    cli_version: input.cliVersion,
+    platform: process.platform,
+    truncated_diff: truncatedDiff,
+    truncated_map: truncatedMap,
+    truncated_screenshot: truncatedScreenshot,
+    truncated_trace: false,
+    parts: [
+      {
+        field: "payload",
+        filename: "payload.json.gz",
+        bytes: payloadBytes.byteLength,
+        sha256: sha256Bytes(payloadBytes),
+      },
+    ],
+  };
+
+  if (payload.description.trim().length > 0) {
+    meta.description = payload.description;
+  }
+
+  const form = new FormData();
+  form.append("meta", JSON.stringify(meta));
+  form.append(
+    "payload",
+    new Blob([Uint8Array.from(payloadBytes)], { type: "application/gzip" }),
+    "payload.json.gz",
+  );
+
+  return form;
+}
+
+function gzipPayload(payload: BugReportPayload): Buffer {
+  return gzipSync(Buffer.from(JSON.stringify(payload)), { level: 9 });
+}
+
+function sha256Bytes(bytes: Uint8Array): string {
+  return createHash("sha256").update(bytes).digest("hex");
+}
+
+// The document is required: a failure to read it makes the attachment
+// unavailable. Each TypeScript module is optional, because a report that loses
+// one module is still better than a report that loses the review.
+function unavailable(attachment: AttachmentName): AttachmentError {
+  return { attachment, error: "unavailable" };
+}
+
+function byAttachment(left: AttachmentError, right: AttachmentError): number {
+  return left.attachment.localeCompare(right.attachment);
+}

package/src/server/client-error-budget.ts

@@ -0,0 +1,45 @@
+// Keeps one repeating error from counting as thousands. The budget is per app
+// session and per message digest, so a loop on one error still lets other
+// errors through, and the burst event says how much was withheld.
+
+export const CLIENT_ERROR_BUDGET_PER_HASH = 5;
+
+const BURST_EVERY = 100;
+
+const DEFAULT_MAX_KEYS = 1_000;
+
+export interface ClientErrorAdmission {
+  verdict: "send" | "burst" | "drop";
+  /** How many reports past the budget this key has seen, including this one. */
+  suppressed: number;
+}
+
+export class ClientErrorBudget {
+  private readonly counts = new Map<string, number>();
+
+  constructor(private readonly maxKeys = DEFAULT_MAX_KEYS) {}
+
+  admit(sessionId: string, messageHash: string): ClientErrorAdmission {
+    const key = `${sessionId}\n${messageHash}`;
+    const count = (this.counts.get(key) ?? 0) + 1;
+    this.counts.delete(key);
+    this.counts.set(key, count);
+
+    while (this.counts.size > this.maxKeys) {
+      const oldest = this.counts.keys().next().value;
+
+      if (oldest === undefined) break;
+      this.counts.delete(oldest);
+    }
+
+    const suppressed = Math.max(0, count - CLIENT_ERROR_BUDGET_PER_HASH);
+
+    if (suppressed === 0) return { verdict: "send", suppressed };
+
+    return {
+      verdict:
+        suppressed === 1 || suppressed % BURST_EVERY === 0 ? "burst" : "drop",
+      suppressed,
+    };
+  }
+}