@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/software-map-topology-diff.ts

@@ -0,0 +1,260 @@
+import type {
+  NormalizedSoftwareElement,
+  NormalizedSoftwareModel,
+  NormalizedSoftwareRelationship,
+  SoftwareChangeStatus,
+} from "./software-map-model";
+
+export interface SoftwareMapElementTopologyChange {
+  path: string;
+  status: Exclude<SoftwareChangeStatus, "unchanged">;
+  label: string;
+  type: NormalizedSoftwareElement["type"];
+  beforeParentPath?: string;
+  afterParentPath?: string;
+}
+
+export interface SoftwareMapRelationshipTopologyChange {
+  key: string;
+  status: Exclude<SoftwareChangeStatus, "unchanged">;
+  from: string;
+  to: string;
+  kind: NormalizedSoftwareRelationship["kind"];
+  label?: string;
+}
+
+export interface SoftwareMapTopologyDiff {
+  elementChanges: SoftwareMapElementTopologyChange[];
+  relationshipChanges: SoftwareMapRelationshipTopologyChange[];
+  elementStatusByPath: Record<
+    string,
+    Exclude<SoftwareChangeStatus, "unchanged">
+  >;
+  counts: {
+    addedElements: number;
+    removedElements: number;
+    modifiedElements: number;
+    addedRelationships: number;
+    removedRelationships: number;
+    modifiedRelationships: number;
+  };
+}
+
+export function diffSoftwareMaps(
+  base: NormalizedSoftwareModel | null | undefined,
+  head: NormalizedSoftwareModel | null | undefined,
+): SoftwareMapTopologyDiff | null {
+  if (!base || !head) return null;
+
+  const elementChanges = diffElements(base, head);
+  const relationshipChanges = diffRelationships(base, head);
+
+  const elementStatusByPath = Object.fromEntries(
+    elementChanges
+      .filter((change) => change.status !== "removed")
+      .map((change) => [change.path, change.status] as const),
+  );
+
+  return {
+    elementChanges,
+    relationshipChanges,
+    elementStatusByPath,
+    counts: {
+      addedElements: elementChanges.filter(
+        (change) => change.status === "added",
+      ).length,
+      removedElements: elementChanges.filter(
+        (change) => change.status === "removed",
+      ).length,
+      modifiedElements: elementChanges.filter(
+        (change) => change.status === "modified",
+      ).length,
+      addedRelationships: relationshipChanges.filter(
+        (change) => change.status === "added",
+      ).length,
+      removedRelationships: relationshipChanges.filter(
+        (change) => change.status === "removed",
+      ).length,
+      modifiedRelationships: relationshipChanges.filter(
+        (change) => change.status === "modified",
+      ).length,
+    },
+  };
+}
+
+function diffElements(
+  base: NormalizedSoftwareModel,
+  head: NormalizedSoftwareModel,
+): SoftwareMapElementTopologyChange[] {
+  const changes: SoftwareMapElementTopologyChange[] = [];
+  const baseByPath = base.elementsByPath;
+  const headByPath = head.elementsByPath;
+
+  for (const headElement of head.elements) {
+    const baseElement = baseByPath.get(headElement.path);
+
+    if (!baseElement) {
+      changes.push(elementChange(headElement, "added"));
+      continue;
+    }
+
+    if (
+      elementTopologySignature(baseElement) !==
+      elementTopologySignature(headElement)
+    ) {
+      changes.push(
+        elementChange(headElement, "modified", {
+          beforeParentPath: baseElement.parentPath,
+          afterParentPath: headElement.parentPath,
+        }),
+      );
+    }
+  }
+
+  for (const baseElement of base.elements) {
+    if (!headByPath.has(baseElement.path)) {
+      changes.push(elementChange(baseElement, "removed"));
+    }
+  }
+
+  return changes.sort(compareElementChanges);
+}
+
+function elementChange(
+  element: NormalizedSoftwareElement,
+  status: Exclude<SoftwareChangeStatus, "unchanged">,
+  extra: Partial<SoftwareMapElementTopologyChange> = {},
+): SoftwareMapElementTopologyChange {
+  return {
+    path: element.path,
+    status,
+    label: element.label,
+    type: element.type,
+    ...extra,
+  };
+}
+
+function elementTopologySignature(element: NormalizedSoftwareElement): string {
+  return JSON.stringify({
+    type: element.type,
+    label: element.label,
+    parentPath: element.parentPath ?? null,
+    external: element.external ?? null,
+    coverage: element.coverage ?? null,
+    sourceRanges: element.sourceRanges ?? null,
+  });
+}
+
+function diffRelationships(
+  base: NormalizedSoftwareModel,
+  head: NormalizedSoftwareModel,
+): SoftwareMapRelationshipTopologyChange[] {
+  const changes: SoftwareMapRelationshipTopologyChange[] = [];
+  const baseByKey = relationshipMap(base.relationships);
+  const headByKey = relationshipMap(head.relationships);
+
+  for (const [key, headRelationship] of headByKey) {
+    const baseRelationship = baseByKey.get(key);
+
+    if (!baseRelationship) {
+      changes.push(relationshipChange(key, headRelationship, "added"));
+      continue;
+    }
+
+    if (
+      relationshipTopologySignature(baseRelationship) !==
+      relationshipTopologySignature(headRelationship)
+    ) {
+      changes.push(relationshipChange(key, headRelationship, "modified"));
+    }
+  }
+
+  for (const [key, baseRelationship] of baseByKey) {
+    if (!headByKey.has(key)) {
+      changes.push(relationshipChange(key, baseRelationship, "removed"));
+    }
+  }
+
+  return changes.sort(compareRelationshipChanges);
+}
+
+function relationshipMap(
+  relationships: readonly NormalizedSoftwareRelationship[],
+): Map<string, NormalizedSoftwareRelationship> {
+  return new Map(
+    relationships.map((relationship) => [
+      relationshipTopologyKey(relationship),
+      relationship,
+    ]),
+  );
+}
+
+function relationshipTopologyKey(
+  relationship: NormalizedSoftwareRelationship,
+): string {
+  return [
+    relationship.from,
+    relationship.to,
+    relationship.kind,
+    relationship.kind === "semantic" ? (relationship.semanticKind ?? "") : "",
+    relationship.kind === "call" ? String(relationship.nthCallSite) : "",
+  ].join("\u0000");
+}
+
+function relationshipTopologySignature(
+  relationship: NormalizedSoftwareRelationship,
+): string {
+  return JSON.stringify({
+    label: relationship.label ?? null,
+    description: relationship.description ?? null,
+    sourceRanges:
+      relationship.kind === "semantic"
+        ? (relationship.sourceRanges ?? null)
+        : null,
+  });
+}
+
+function relationshipChange(
+  key: string,
+  relationship: NormalizedSoftwareRelationship,
+  status: Exclude<SoftwareChangeStatus, "unchanged">,
+): SoftwareMapRelationshipTopologyChange {
+  return {
+    key,
+    status,
+    from: relationship.from,
+    to: relationship.to,
+    kind: relationship.kind,
+    label: relationship.label,
+  };
+}
+
+function compareElementChanges(
+  left: SoftwareMapElementTopologyChange,
+  right: SoftwareMapElementTopologyChange,
+) {
+  return (
+    statusOrder(left.status) - statusOrder(right.status) ||
+    left.path.localeCompare(right.path)
+  );
+}
+
+function compareRelationshipChanges(
+  left: SoftwareMapRelationshipTopologyChange,
+  right: SoftwareMapRelationshipTopologyChange,
+) {
+  return (
+    statusOrder(left.status) - statusOrder(right.status) ||
+    left.from.localeCompare(right.from) ||
+    left.to.localeCompare(right.to) ||
+    left.key.localeCompare(right.key)
+  );
+}
+
+function statusOrder(status: Exclude<SoftwareChangeStatus, "unchanged">) {
+  if (status === "added") return 0;
+
+  if (status === "modified") return 1;
+
+  return 2;
+}

package/src/source.ts

@@ -0,0 +1,92 @@
+import { z } from "zod";
+
+const label = z.string().trim().min(1);
+
+/** The repository and commits one source reference was read from. A
+ * reference without pins resolves against its document's pins; one with
+ * pins names them itself, so a document can quote several repositories or
+ * commits. `base` is only needed by references to the base side. */
+export const sourcePinsSchema = z.strictObject({
+  repositoryId: label,
+  head: label,
+  base: label.optional(),
+});
+
+export type SourcePins = z.infer<typeof sourcePinsSchema>;
+
+/** Internal coordinates for reading one revision or storing resolved coverage.
+ * Authored document attachments use DiffSelection instead. */
+export const fileLineRangeSchema = z
+  .strictObject({
+    side: z.enum(["base", "head"]).default("head"),
+    file: label,
+    fromLine: z.number().int().positive(),
+    toLine: z.number().int().positive(),
+    pins: sourcePinsSchema.optional(),
+  })
+  .refine((s) => s.toLine >= s.fromLine, "Source range ends before it starts.")
+  .refine(
+    (s) => s.side === "head" || !s.pins || s.pins.base !== undefined,
+    "A base-side source needs base pins.",
+  );
+
+export type FileLineRange = z.infer<typeof fileLineRangeSchema>;
+
+export type SourceRange = Pick<FileLineRange, "file" | "fromLine" | "toLine">;
+
+/** Thrown by the pure checks; each boundary translates it for its clients. */
+export class SourceRangeError extends Error {}
+
+/** Git and jj read committed objects, so a lexical check suffices: nothing
+ * here follows a working-copy symlink. An empty string names the root. */
+export function checkSourcePath(file: string): void {
+  if (
+    file.startsWith("/") ||
+    file.includes("\\") ||
+    file.split("/").some((part) => part === ".." || part === ".") ||
+    /[\u0000-\u001f]/.test(file)
+  )
+    throw new SourceRangeError(
+      "Source file must be a repository-relative path.",
+    );
+}
+
+/** The range's text from a whole file. A trailing newline is not a line. */
+export function sliceSourceRange(text: string, range: SourceRange): string {
+  const lines = text.split(/\r?\n/);
+
+  if (text.endsWith("\n")) lines.pop();
+
+  if (text === "" || range.toLine > lines.length)
+    throw new SourceRangeError(
+      `Source range ${range.file}:${range.fromLine}-${range.toLine} exceeds the pinned file (${lines.length} lines).`,
+    );
+
+  return lines.slice(range.fromLine - 1, range.toLine).join("\n");
+}
+
+/** A source shown as a peek must contain visible text; a whitespace-only
+ * range is an authoring mistake. Prose links may point at blank lines, so
+ * only peek-rendering references call this. */
+export function requireVisibleSource(text: string, range: SourceRange): void {
+  if (text.trim() === "")
+    throw new SourceRangeError(
+      `Source range ${range.file}:${range.fromLine}-${range.toLine} contains only whitespace.`,
+    );
+}
+
+/** The authoring input names the diff side `graph`; the document names it
+ * `side`. */
+export function codePeekSource(props: {
+  file: string;
+  fromLine: number;
+  toLine: number;
+  graph?: "head" | "base";
+}): FileLineRange {
+  return {
+    side: props.graph ?? "head",
+    file: props.file,
+    fromLine: props.fromLine,
+    toLine: props.toLine,
+  };
+}

package/src/startup-trace.ts

@@ -0,0 +1,232 @@
+// CLI profiling instrumentation. Enabled when either variable is set:
+//
+//   DEV_FAST_REVIEW_TRACE=<file>     write this process's span tree to <file>
+//   DEV_FAST_REVIEW_TRACE_DIR=<dir>  write one file per process into <dir>
+//
+// Otherwise every helper is a zero-cost passthrough. Spans are wall-clock
+// intervals (ms since process start, i.e. performance.timeOrigin) with parent
+// links propagated through async context, so concurrent work (graph prewarm,
+// browser requests, parallel worktree creation) nests correctly. The whole
+// span tree is flushed as JSON on process exit.
+//
+// The directory form suits runs of many `review` commands (some delegated to a
+// second process): each one lands in its own file, which a caller can join
+// back to what launched it by wall-clock (`timeOrigin`) and `argv`.
+import { AsyncLocalStorage } from "node:async_hooks";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { performance } from "node:perf_hooks";
+
+import { setLocalVcsCommandObserver } from "@dev.fast/local-vcs";
+import { errorMessage } from "@dev.fast/trace-core";
+
+interface TraceSpanRecord {
+  id: number;
+  parentId: number | null;
+  name: string;
+  detail?: string;
+  start: number;
+  end: number | null;
+  ok?: boolean;
+}
+
+const TRACE_FILE_ENV = "DEV_FAST_REVIEW_TRACE";
+
+const TRACE_DIR_ENV = "DEV_FAST_REVIEW_TRACE_DIR";
+
+const traceFile = resolveTraceFile(process.env);
+
+export const traceEnabled = Boolean(traceFile);
+
+const spans: TraceSpanRecord[] = [];
+
+const attributes: Record<string, string | number | boolean> = {};
+
+let nextId = 1;
+
+const context = new AsyncLocalStorage<number>();
+
+interface SpanHandle {
+  id: number;
+  end: (detail?: string) => void;
+  fail: (detail?: string) => void;
+}
+
+const NOOP_HANDLE: SpanHandle = { id: 0, end: () => {}, fail: () => {} };
+
+// Manual span: caller owns the lifetime and (optionally) the parent. Used for
+// spans whose start/end don't wrap a single function call (HTTP requests,
+// "waiting for submission").
+export function startSpan(
+  name: string,
+  options: { parentId?: number | null; detail?: string } = {},
+): SpanHandle {
+  if (!traceEnabled) return NOOP_HANDLE;
+
+  const record: TraceSpanRecord = {
+    id: nextId++,
+    parentId:
+      options.parentId !== undefined
+        ? options.parentId
+        : (context.getStore() ?? null),
+    name,
+    detail: options.detail,
+    start: performance.now(),
+    end: null,
+  };
+
+  spans.push(record);
+
+  return {
+    id: record.id,
+    end: (detail) => {
+      if (record.end === null) record.end = performance.now();
+
+      if (detail) record.detail = detail;
+    },
+    fail: (detail) => {
+      if (record.end === null) record.end = performance.now();
+      record.ok = false;
+
+      if (detail) record.detail = detail;
+    },
+  };
+}
+
+// Wrap an async (or sync) call; children created inside inherit this span as
+// their parent via AsyncLocalStorage. A thrown error marks the span failed.
+export async function span<T>(
+  name: string,
+  fn: () => Promise<T> | T,
+  detail?: string,
+): Promise<T> {
+  if (!traceEnabled) return fn();
+  const handle = startSpan(name, { detail });
+
+  try {
+    const result = await context.run(handle.id, fn);
+    handle.end();
+
+    return result;
+  } catch (error) {
+    handle.fail(errorMessage(error));
+    throw error;
+  }
+}
+
+// Subprocess span. Name is `$ <cmd>` truncated; detail carries the full
+// command line and cwd so the harness can group by executable and verb.
+export function traceCommand<T>(
+  file: string,
+  args: string[],
+  fn: () => Promise<T>,
+  options: { cwd?: string } = {},
+): Promise<T> {
+  return span(
+    commandSpanName(file, args),
+    fn,
+    commandDetail(file, args, options.cwd),
+  );
+}
+
+// Zero-duration marker (e.g. "browser websocket connected").
+export function traceEvent(
+  name: string,
+  options: { parentId?: number | null; detail?: string } = {},
+): void {
+  startSpan(name, options).end();
+}
+
+// Process-wide attributes (command path, command run id, review uuid) that
+// the harness uses to join this trace to telemetry and to the agent's tool
+// call.
+export function setTraceAttribute(
+  key: string,
+  value: string | number | boolean,
+): void {
+  if (!traceEnabled) return;
+  attributes[key] = value;
+}
+
+function flushTrace(): void {
+  if (!traceEnabled || !traceFile) return;
+  const now = performance.now();
+
+  try {
+    mkdirSync(path.dirname(traceFile), { recursive: true });
+    writeFileSync(
+      traceFile,
+      `${JSON.stringify({
+        timeOrigin: performance.timeOrigin,
+        pid: process.pid,
+        ppid: process.ppid,
+        argv: process.argv,
+        cwd: process.cwd(),
+        delegated: Boolean(process.env.DEV_FAST_REVIEW_CLI_DELEGATED),
+        attributes,
+        durationMs: now,
+        spans: spans.map((record) => ({
+          ...record,
+          end: record.end ?? now,
+          openAtExit: record.end === null || undefined,
+        })),
+      })}\n`,
+      "utf8",
+    );
+  } catch {
+    // Profiling must never break the CLI.
+  }
+}
+
+function commandSpanName(file: string, args: string[]): string {
+  return `$ ${[path.basename(file), ...args].join(" ").slice(0, 100)}`;
+}
+
+function commandDetail(
+  file: string,
+  args: string[],
+  cwd: string | undefined,
+): string {
+  const line = [file, ...args].join(" ");
+
+  return cwd ? `${line}\n(cwd ${cwd})` : line;
+}
+
+function resolveTraceFile(env: NodeJS.ProcessEnv): string | undefined {
+  const file = env[TRACE_FILE_ENV]?.trim();
+
+  if (file) return file;
+  const dir = env[TRACE_DIR_ENV]?.trim();
+
+  if (!dir) return undefined;
+
+  const argvSlug = process.argv
+    .slice(2)
+    .filter((arg) => !arg.startsWith("-"))
+    .slice(0, 3)
+    .join("-")
+    .replace(/[^A-Za-z0-9_.-]+/g, "_")
+    .slice(0, 60);
+
+  const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+
+  return path.join(
+    dir,
+    `${stamp}-${process.pid}${argvSlug ? `-${argvSlug}` : ""}.json`,
+  );
+}
+
+if (traceEnabled) {
+  process.on("exit", flushTrace);
+  // Every git/jj spawn inside @dev.fast/local-vcs becomes a `$ …` span under
+  // whatever span is active in the caller's async context.
+  setLocalVcsCommandObserver({
+    start({ file, args, cwd }) {
+      const handle = startSpan(commandSpanName(file, args), {
+        detail: commandDetail(file, args, cwd),
+      });
+
+      return ({ ok }) => (ok ? handle.end() : handle.fail());
+    },
+  });
+}