@dev.fast/whiteboard 0.0.0-stage → 0.2.0

package/src/review-api/blocks/index.ts

@@ -0,0 +1,90 @@
+import { z } from "zod";
+
+import { call_stack_diff } from "./call_stack_diff.js";
+import { type CalloutBlock, callout, calloutSchema } from "./callout.js";
+import { code } from "./code.js";
+import { code_peek } from "./code_peek.js";
+import { database_lens } from "./database_lens.js";
+import type { BlockDefinition } from "./definition.js";
+import { divider } from "./divider.js";
+import { flow_diagram } from "./flow_diagram.js";
+import { image } from "./image.js";
+import { markdown } from "./markdown.js";
+import { type SectionBlock, section, sectionSchema } from "./section.js";
+import { sequence } from "./sequence.js";
+import { software_map } from "./software_map.js";
+import { trace_quote } from "./trace_quote.js";
+import { type TutorialBlock, tutorial, tutorialSchema } from "./tutorial.js";
+
+/** Leaf kinds share one discriminated union so unknown types read as they always have. */
+export const leafSchema = z.discriminatedUnion("type", [
+  markdown.schema,
+  code.schema,
+  divider.schema,
+  code_peek.schema,
+  sequence.schema,
+  call_stack_diff.schema,
+  database_lens.schema,
+  image.schema,
+  trace_quote.schema,
+  software_map.schema,
+  flow_diagram.schema,
+]);
+
+export type LeafBlock = z.infer<typeof leafSchema>;
+
+export type Block = LeafBlock | SectionBlock | CalloutBlock | TutorialBlock;
+
+export type BlockType = Block["type"];
+
+export type Definitions = {
+  [K in BlockType]: BlockDefinition<Extract<Block, { type: K }>>;
+};
+
+/** Every block kind, keyed by type. A kind without a definition is a compile error. */
+export const blocks = {
+  markdown,
+  code,
+  divider,
+  code_peek,
+  sequence,
+  call_stack_diff,
+  database_lens,
+  image,
+  trace_quote,
+  software_map,
+  flow_diagram,
+  section,
+  callout,
+  tutorial,
+} satisfies Definitions;
+
+/** Discriminated by type, so a malformed block reports its own kind's
+ * issues rather than every kind's. */
+export const blockSchema: z.ZodType<Block> = z.lazy(() =>
+  z.discriminatedUnion("type", blockKindSchemas()),
+);
+
+/** Each block kind's schema, for unions that add kinds of their own. Read
+ * lazily: the container modules import this one. */
+export const blockKindSchemas = () =>
+  [leafSchema, sectionSchema, calloutSchema, tutorialSchema] as const;
+
+function checkBlock<K extends BlockType>(
+  type: K,
+  block: Extract<Block, { type: K }>,
+): void {
+  const definition: Definitions[K] = blocks[type];
+  definition.check?.(block);
+}
+
+/** Relationships not expressible in a field schema. Sources/resources are checked by host providers. */
+export function checkReferences(document: Block[]): void {
+  const visit = (block: Block) => {
+    checkBlock(block.type, block);
+
+    if ("children" in block) block.children.forEach(visit);
+  };
+
+  document.forEach(visit);
+}

package/src/review-api/blocks/markdown.ts

@@ -0,0 +1,17 @@
+import { sourcePinsSchema } from "@review/source.js";
+
+import { defineBlock, text } from "./definition.js";
+
+export const markdown = {
+  type: "markdown",
+  schema: defineBlock("markdown", {
+    markdown: text.describe(
+      "Safe Markdown. Repository file links must use [label](review-source:head/path#L10-L24) or review-source:base/path#L10-L24, with a repository-relative path and verified line numbers. Relative paths, absolute filesystem paths, and file/editor URLs are rejected. External links use https://, http://, or mailto:; document anchors use #heading.",
+    ),
+    pins: sourcePinsSchema
+      .optional()
+      .describe(
+        "Repository and commits this block's review-source links resolve against, instead of the document's pins.",
+      ),
+  }),
+} as const;

package/src/review-api/blocks/section.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+import { type BlockDefinition, defineBlock, label } from "./definition.js";
+import { type Block, blockSchema } from "./index.js";
+
+export interface SectionBlock {
+  id?: string;
+  type: "section";
+  title: string;
+  defaultCollapsed?: boolean;
+  children: Block[];
+}
+
+// blockSchema is read inside z.lazy, after every module in the cycle has evaluated.
+export const sectionSchema = defineBlock("section", {
+  title: label,
+  defaultCollapsed: z.boolean().optional(),
+  children: z.array(z.lazy((): z.ZodType<Block> => blockSchema)),
+});
+
+export const section: BlockDefinition<SectionBlock> = {
+  type: "section",
+  schema: sectionSchema,
+};

package/src/review-api/blocks/sequence.ts

@@ -0,0 +1,56 @@
+import { anchorSchema } from "@review/lens-selection.js";
+import { z } from "zod";
+
+import { codeFields } from "./code.js";
+import {
+  type BlockDefinition,
+  defineBlock,
+  elementPins,
+  identity,
+  label,
+  requireKey,
+  text,
+} from "./definition.js";
+
+export const stepSchema = z
+  .strictObject({
+    ...identity,
+    type: z.literal("step").default("step"),
+    from: label,
+    to: label,
+    label,
+    style: z.enum(["call", "return", "async"]).default("call"),
+    source: anchorSchema.optional(),
+    pins: elementPins,
+    explanation: label.optional(),
+    code: z.strictObject(codeFields).optional(),
+  })
+  .refine(
+    (s) =>
+      [s.source, s.explanation, s.code].filter((v) => v !== undefined)
+        .length === 1,
+    "A step needs exactly one of source, explanation, or code.",
+  );
+
+export type Step = z.infer<typeof stepSchema>;
+
+/** Kept for callers that parsed sequences directly. */
+export const sequenceSchema = defineBlock("sequence", {
+  title: label,
+  actors: z.record(text, label),
+  steps: z.array(stepSchema),
+  pins: elementPins,
+});
+
+export type SequenceBlock = z.infer<typeof sequenceSchema>;
+
+export const sequence = {
+  type: "sequence",
+  schema: sequenceSchema,
+  check(block: SequenceBlock) {
+    for (const step of block.steps) {
+      requireKey(block.actors, step.from);
+      requireKey(block.actors, step.to);
+    }
+  },
+} satisfies BlockDefinition<SequenceBlock>;

package/src/review-api/blocks/software_map.ts

@@ -0,0 +1,9 @@
+import { defineBlock, label } from "./definition.js";
+
+export const software_map = {
+  type: "software_map",
+  schema: defineBlock("software_map", {
+    mapVersionId: label,
+    focusElementId: label.optional(),
+  }),
+} as const;

package/src/review-api/blocks/trace_quote.ts

@@ -0,0 +1,10 @@
+import { defineBlock, label } from "./definition.js";
+
+export const trace_quote = {
+  type: "trace_quote",
+  schema: defineBlock("trace_quote", {
+    traceId: label,
+    eventId: label,
+    text: label,
+  }),
+} as const;

package/src/review-api/blocks/tutorial.ts

@@ -0,0 +1,39 @@
+import {
+  type TutorialAuthoringConversation,
+  tutorialAuthoringConversationSchema,
+} from "@review/tutorial-conversation.js";
+import { z } from "zod";
+
+import { type BlockDefinition, defineBlock } from "./definition.js";
+import { type Block, blockSchema } from "./index.js";
+
+type TutorialContent =
+  | { kind: "keymap" }
+  | { kind: "conversation"; conversation: TutorialAuthoringConversation }
+  | { kind: "view"; view: "review" | "commits" | "diff" | "map"; label: string }
+  | { kind: "feature"; feature: "softwareMap"; children: Block[] };
+
+export type TutorialBlock = { id?: string; type: "tutorial" } & TutorialContent;
+
+export const tutorialSchema = z.discriminatedUnion("kind", [
+  defineBlock("tutorial", { kind: z.literal("keymap") }),
+  defineBlock("tutorial", {
+    kind: z.literal("conversation"),
+    conversation: tutorialAuthoringConversationSchema,
+  }),
+  defineBlock("tutorial", {
+    kind: z.literal("view"),
+    view: z.enum(["review", "commits", "diff", "map"]),
+    label: z.string(),
+  }),
+  defineBlock("tutorial", {
+    kind: z.literal("feature"),
+    feature: z.literal("softwareMap"),
+    children: z.array(z.lazy((): z.ZodType<Block> => blockSchema)),
+  }),
+]);
+
+export const tutorial: BlockDefinition<TutorialBlock> = {
+  type: "tutorial",
+  schema: tutorialSchema,
+};

package/src/review-api/checkout-fs.ts

@@ -0,0 +1,14 @@
+import * as fs from "node:fs/promises";
+import { createRequire } from "node:module";
+
+/**
+ * File system calls for paths inside a user's checkout. Electron's `fs`
+ * treats every `*.asar` path as an archive, so a checkout that merely
+ * contains one fails with "Invalid package" or shows it as a directory.
+ * Electron's unpatched `original-fs` reads it as the plain file it is.
+ */
+export const checkoutFs: typeof fs = process.versions.electron
+  ? // SAFETY: Electron's original-fs is Node's fs module without the asar patch.
+    (createRequire(import.meta.url)("original-fs") as typeof import("node:fs"))
+      .promises
+  : fs;

package/src/review-api/client.ts

@@ -0,0 +1 @@
+export { ReviewApiClient, ReviewApiError } from "@dev.fast/review-protocol";

package/src/review-api/comparison-coverage.ts

@@ -0,0 +1,304 @@
+import { createHash } from "node:crypto";
+
+import {
+  type StructuralDiff,
+  type StructuralRegion,
+  type StructuralSource,
+  type StructuralVisibility,
+  structuralRows,
+} from "@dev.fast/review-protocol";
+import type { AlignmentRow } from "@review/lens-selection.js";
+import type { FileLineRange } from "@review/source.js";
+import { parseUnifiedPatch } from "@review/unified-diff.js";
+import {
+  type Coverage,
+  type CoverageFile,
+  type LineInterval,
+  emptyCoverage,
+  intersectIntervals,
+  subtractIntervals,
+  unionIntervals,
+} from "@review/viewed-coverage.js";
+
+import type { Pins } from "./document.js";
+import { textualRows } from "./lens-alignment.js";
+import type { LocalReviewData } from "./local-data.js";
+
+export type CoverageMode = "structural" | "textual";
+
+const hash = (parts: (string | null)[]) =>
+  createHash("sha256").update(JSON.stringify(parts)).digest("hex");
+
+export interface ComparisonCoverage {
+  files: CoverageFile[];
+  fileSources: Map<string, FileLineRange[]>;
+  alignments: Map<string, readonly AlignmentRow[]>;
+}
+
+/** Immutable comparison facts shared by catalog totals and review progress. */
+export async function comparisonCoverage(
+  data: LocalReviewData,
+  reviewId: string,
+  pins: Pins,
+  mode: CoverageMode,
+  signal: AbortSignal,
+  publish?: (coverage: ComparisonCoverage) => void,
+) {
+  const fileSources = new Map<string, FileLineRange[]>();
+  const alignments = new Map<string, readonly AlignmentRow[]>();
+
+  const files: CoverageFile[] = [];
+
+  if (mode === "textual") {
+    for (const file of await data.changes(pins)) {
+      signal.throwIfAborted();
+      const patch = await data.changes(pins, file.path);
+      const changed = emptyCoverage();
+
+      for (const hunk of parseUnifiedPatch(file.path, patch))
+        for (const line of hunk.lines) {
+          if (line.kind === "add")
+            changed.head.push([line.newLine! - 1, line.newLine!]);
+
+          if (line.kind === "remove")
+            changed.base.push([line.oldLine! - 1, line.oldLine!]);
+        }
+
+      changed.base = unionIntervals(changed.base);
+      changed.head = unionIntervals(changed.head);
+
+      const [base, head] = await Promise.all([
+        file.status === "added"
+          ? null
+          : data
+              .file(pins, "base", file.previousPath ?? file.path)
+              .then((value) => value.text)
+              .catch(() => null),
+        file.status === "deleted"
+          ? null
+          : data
+              .file(pins, "head", file.path)
+              .then((value) => value.text)
+              .catch(() => null),
+      ]);
+
+      alignments.set(
+        file.path,
+        textualRows(
+          file.path,
+          patch,
+          base === null ? 0 : base.split("\n").length,
+          head === null ? 0 : head.split("\n").length,
+        ),
+      );
+
+      const readable =
+        (file.status === "added" || base !== null) &&
+        (file.status === "deleted" || head !== null);
+
+      const fingerprint = hash([
+        pins.repositoryId,
+        base,
+        head,
+        ...(readable ? [] : [pins.base, pins.head, patch]),
+      ]);
+
+      fileSources.set(file.path, [
+        ...(base !== null
+          ? [
+              {
+                side: "base" as const,
+                file: file.previousPath ?? file.path,
+                fromLine: 1,
+                toLine: base.split("\n").length,
+              },
+            ]
+          : []),
+        ...(head !== null
+          ? [
+              {
+                side: "head" as const,
+                file: file.path,
+                fromLine: 1,
+                toLine: head.split("\n").length,
+              },
+            ]
+          : []),
+      ]);
+      files.push({
+        path: file.path,
+        previousPath: file.previousPath,
+        fingerprint,
+        changed,
+        viewed: emptyCoverage(),
+      });
+      publish?.({
+        files: [...files],
+        fileSources: new Map(fileSources),
+        alignments: new Map(alignments),
+      });
+    }
+  } else {
+    const remaining = new Set<string>();
+
+    for await (const event of data.structuralChanges({
+      reviewId,
+      pins,
+      signal,
+    })) {
+      if (event.type === "start") {
+        for (const entry of event.files)
+          remaining.add((entry.file.rhs ?? entry.file.lhs)!.path);
+
+        if (!remaining.size) break;
+        continue;
+      }
+
+      if (event.type === "complete" && (event.failed || event.aborted))
+        throw new Error(
+          event.aborted?.message ?? "Structural coverage is incomplete.",
+        );
+
+      if (event.type !== "file") continue;
+
+      const path = (event.file.rhs ?? event.file.lhs)!.path;
+
+      if (!remaining.delete(path))
+        throw new Error(`Unexpected structural result: ${path}`);
+
+      if (event.error) {
+        if (event.error.code !== "unsupported_file_type")
+          throw new Error(`Cannot count ${path}: ${event.error.message}`);
+
+        if (!remaining.size) break;
+        continue;
+      }
+
+      const diff = event.diff;
+
+      const previousPath =
+        event.file.lhs?.path !== path ? event.file.lhs?.path : undefined;
+
+      const base = diff.type === "text" ? (diff.lhs?.text ?? null) : null;
+      const head = diff.type === "text" ? (diff.rhs?.text ?? null) : null;
+
+      const fingerprint = hash([
+        pins.repositoryId,
+        base,
+        head,
+        ...(diff.type === "binary"
+          ? [event.file.lhs?.oid ?? null, event.file.rhs?.oid ?? null]
+          : []),
+      ]);
+
+      const sources: FileLineRange[] = [];
+
+      if (base !== null)
+        sources.push({
+          side: "base",
+          file: event.file.lhs!.path,
+          fromLine: 1,
+          toLine: base.split("\n").length,
+        });
+
+      if (head !== null)
+        sources.push({
+          side: "head",
+          file: path,
+          fromLine: 1,
+          toLine: head.split("\n").length,
+        });
+      fileSources.set(path, sources);
+
+      if (diff.type === "text") alignments.set(path, structuralRows(diff));
+      files.push({
+        path,
+        previousPath,
+        fingerprint,
+        changed:
+          diff.type === "text" ? diff.structural_changes : emptyCoverage(),
+        folded: foldedChanges(event.visibility, diff),
+        viewed: emptyCoverage(),
+      });
+      publish?.({
+        files: [...files],
+        fileSources: new Map(fileSources),
+        alignments: new Map(alignments),
+      });
+
+      if (!remaining.size) break;
+    }
+
+    if (remaining.size) throw new Error("Structural coverage is incomplete.");
+  }
+
+  return { files, fileSources, alignments };
+}
+
+/**
+ * The changed lines diffr folds by default. A file it hides (lockfiles,
+ * generated, vendored and test files, per its plugins) folds all of them.
+ * Otherwise they are the changed lines under regions that start collapsed
+ * and in no visible leaf: `structural_changes` less what diffr counts in
+ * `stats.visible`, recomputed the way diffr's `change_coverage` does so that
+ * the lines, not just the counts, are known. A paired leaf contributes its
+ * changed spans' lines; an unpaired leaf, all of its lines.
+ */
+export function foldedChanges(
+  visibility: StructuralVisibility | undefined,
+  diff: StructuralDiff,
+): Coverage {
+  if (diff.type !== "text") return emptyCoverage();
+  const all = diff.structural_changes;
+
+  if (visibility?.collapsed)
+    return { base: unionIntervals(all.base), head: unionIntervals(all.head) };
+
+  const side = (
+    changed: readonly LineInterval[],
+    source: StructuralSource | undefined,
+    other: StructuralSource | undefined,
+  ): LineInterval[] => {
+    const paired = new Set<number>();
+
+    const pair = (region: StructuralRegion) => {
+      if (region.kind === "leaf") paired.add(region.alignment_id);
+      else region.children.forEach(pair);
+    };
+
+    other?.regions?.forEach(pair);
+
+    const hidden: LineInterval[] = [],
+      visible: LineInterval[] = [];
+
+    const collect = (region: StructuralRegion, folded: boolean) => {
+      folded ||= region.visibility?.collapsed === true;
+
+      if (region.kind === "fold") {
+        for (const child of region.children) collect(child, folded);
+
+        return;
+      }
+
+      const lines = folded ? hidden : visible;
+
+      if (paired.has(region.alignment_id))
+        for (const span of region.changed ?? [])
+          lines.push([span.line, span.line + 1]);
+      else
+        lines.push([
+          region.start.line,
+          region.end.column === 0 ? region.end.line : region.end.line + 1,
+        ]);
+    };
+
+    for (const region of source?.regions ?? []) collect(region, false);
+
+    return subtractIntervals(intersectIntervals(changed, hidden), visible);
+  };
+
+  return {
+    base: side(all.base, diff.lhs, diff.rhs),
+    head: side(all.head, diff.rhs, diff.lhs),
+  };
+}

package/src/review-api/component-reference.ts

@@ -0,0 +1,30 @@
+/** Every component's fields, for session_get_instructions: the edit tool's
+ * description must stay short enough that clients don't cut it off. */
+export const COMPONENT_REFERENCE = [
+  "## Components",
+  "",
+  "session_edit's content is one component, named by its type. Fields, with ? for optional and anchor for a source anchor string:",
+  "",
+  "- markdown {markdown, pins?}",
+  "- code {text, language?, caption?}",
+  "- divider {}",
+  "- code_peek {source: anchor, caption?, pins?}",
+  "- section {title, children: component[], defaultCollapsed?}",
+  "- callout {children: component[], title?, tone?: info|warning|danger|success}",
+  "- image {assetId from session_upload, alt, caption?}",
+  "- trace_quote {traceId, eventId, text}",
+  "- software_map {mapVersionId, focusElementId?}",
+  "- sequence {title, actors: {key: label}, steps: step[], pins?}",
+  "- step {from, to (actor keys), label, style?: call|return|async, and exactly one of source: anchor, explanation, or code: {text, language?}; pins?}",
+  "- flow_diagram {title, nodes: flow_node[] (1 to 100), edges: flow_edge[], description?, direction?: right|down, pins?}",
+  "- flow_node {key, label, description?, kind?: process|decision|terminal, attachments?: {label, sources: anchor[], pins?}[], link?: {from or to, label?, style?}}",
+  "- flow_edge {from, to (node keys), label?, style?: solid|dashed}",
+  "- call_stack_diff {title, base: frame[], head: frame[], pins?}; either side may be empty",
+  "- frame {source: anchor, label?, key?, parentKey? (an earlier frame on that side), callSite?: anchor, contextSources?: anchor[], via?: {kind: call|queue|callback|rpc, reason}, pins?}",
+  "- database_lens {title, actors: {key: label}, stores: {key: store}, useCases: useCase[] (1 or more), pins?}",
+  "- store {label, storage: relational|document, collections: {key: {label, fields: {key: field}}}, dataStoreKind?: database|objectStore|bucket|artifactStore|fileStore}",
+  "- field {label, dataType, nullable?, primaryKey?, references?: {store, collection, field}, fields?: {key: field}}",
+  "- useCase {label, summary?, operations: operation[] (1 or more)}; operation {kind: read|write, actor, store, collection, label, source: anchor, field?, detail?, pins?}, naming declared keys",
+  "",
+  'Example (replace its path and lines with verified ones): {"type":"sequence","title":"Request","actors":{"a":"Client","b":"Server"},"steps":[{"from":"a","to":"b","label":"Send","source":"head/src/app.ts#L10-L20"}]}',
+].join("\n");