@dev.fast/whiteboard 0.3.3 → 0.3.4-preview.20261019.126

package/src/review-api/document-text.ts

@@ -1,3 +1,5 @@
+import { boardTitle } from "@dev.fast/review-protocol";
+
 import {
   type Element,
   ReviewInputError,
@@ -6,11 +8,22 @@ import {
 } from "./document.js";
 import type { Snapshot } from "./store.js";
 
+interface RelatedBoard {
+  id: string;
+  title: string;
+}
+
 /** A reading view of saved content, not another document format to maintain. */
 export function documentText(
   snapshot: Snapshot,
   targetId?: string,
   full = false,
+  /** Where the whiteboard sits among its project's, by title. */
+  relations?: {
+    parent?: RelatedBoard;
+    children: RelatedBoard[];
+    dependsOn: RelatedBoard[];
+  },
 ): string {
   const target =
     targetId === undefined
@@ -22,11 +35,27 @@ export function documentText(
   const detailed = full || target !== undefined;
 
   const lines = [
-    `# ${snapshot.title}`,
+    `# ${boardTitle(snapshot.title)}`,
     `Session ${snapshot.reviewId} · version ${snapshot.version}`,
-    "",
   ];
 
+  if (relations && targetId === undefined) {
+    const list = (boards: RelatedBoard[]) =>
+      boards
+        .map((board) => `${boardTitle(board.title)} (${board.id})`)
+        .join(", ");
+
+    if (relations.parent) lines.push(`Parent: ${list([relations.parent])}`);
+
+    if (relations.children.length)
+      lines.push(`Children, in order: ${list(relations.children)}`);
+
+    if (relations.dependsOn.length)
+      lines.push(`Depends on: ${list(relations.dependsOn)}`);
+  }
+
+  lines.push("");
+
   const write = (depth: number, text: string) => {
     for (const line of text.split("\n")) lines.push("  ".repeat(depth) + line);
   };

package/src/review-api/document.ts

@@ -1,6 +1,8 @@
+import { type JsonValue, isStringValue } from "@dev.fast/json";
 import {
   type Anchor,
   type LensSource,
+  commitLinkTarget,
   parseAnchor,
   selectionProblem,
   sourceAnchors,
@@ -144,6 +146,11 @@ const targets = <Repository extends Record<string, z.ZodType>>(
   repository: Repository,
 ) =>
   z.discriminatedUnion("kind", [
+    /** The project of the repository, no change: a plan. */
+    z.strictObject({
+      kind: z.literal("project"),
+      ...repository,
+    }),
     z.strictObject({
       kind: z.literal("worktree"),
       ...repository,
@@ -159,8 +166,16 @@ const targets = <Repository extends Record<string, z.ZodType>>(
 
 export const reviewTargetSchema = targets({ repositoryId: label });
 
-/** How agents name a target: by the checkout's path, registered on acceptance. */
-export const pathTargetSchema = targets({ repositoryPath: label });
+/** Targets as agents write them: a checkout path instead of a repository id,
+ * plus a PR by URL or number. */
+export const pathTargetSchema = z.discriminatedUnion("kind", [
+  ...targets({ repositoryPath: label }).options,
+  z.strictObject({
+    kind: z.literal("pullRequest"),
+    repositoryPath: label,
+    pullRequest: z.union([label, z.number().int().positive()]),
+  }),
+]);
 
 export type ReviewTarget = z.infer<typeof reviewTargetSchema>;
 
@@ -175,11 +190,99 @@ const unitTypes = new Set(["step", "flow_node", "flow_edge"]);
 export const isUnit = (element: Element): element is Unit =>
   unitTypes.has(element.type);
 
+/** Rewrites old review-source: and review-trace: links to their whiteboard: form. */
+export function canonicalLink(href: string): string {
+  return href.replace(
+    /^review-(source|trace):/i,
+    (_, kind: string) => `whiteboard:${kind.toLowerCase()}/`,
+  );
+}
+
+/** Markdown link destinations and definitions that begin with `target`, a
+ * regex source; the match's first group is what comes before it. */
+const linkDestination = (target: string) =>
+  new RegExp(String.raw`(\]\(\s*<?|^\s*\[[^\]\n]+\]:\s*<?)` + target, "gim");
+
+/** Every Markdown text in `value`, rewritten. */
+function rewriteMarkdown<T>(
+  value: T,
+  rewrite: (markdown: string) => string,
+): T {
+  // SAFETY: a JSON round trip of stored or parsed JSON, rewriting only
+  // Markdown text.
+  return JSON.parse(JSON.stringify(value), (key, field: JsonValue) =>
+    key === "markdown" && isStringValue(field) ? rewrite(field) : field,
+  ) as T;
+}
+
+const retiredLinks = linkDestination("review-(source|trace):");
+
+/** Rewrites old link prefixes in Markdown link destinations and definitions. */
+export function respellLinks(markdown: string): string {
+  return markdown.replace(
+    retiredLinks,
+    (_, before: string, kind: string) =>
+      `${before}whiteboard:${kind.toLowerCase()}/`,
+  );
+}
+
+/** Every Markdown text in `document` with its links spelled the current
+ * way. */
+export function respellDocumentLinks<T>(document: T): T {
+  return rewriteMarkdown(document, respellLinks);
+}
+
+export function respellEditLinks(edit: Edit): Edit {
+  return rewriteMarkdown(edit, respellLinks);
+}
+
+/** Names a block from outside its board. Block ids are unique only within a board. */
+export type BlockRef = { board: string; block: string };
+
+export type BoardRef = BlockRef | { board: string; block?: undefined };
+
+/** Parses whiteboard:board/<id> or whiteboard:board/<id>#<blockId>. */
+export function boardLink(href: string): BoardRef | undefined {
+  const match = /^whiteboard:board\/([^#/]+)(?:#(.+))?$/.exec(href);
+
+  if (!match) return undefined;
+
+  try {
+    const board = decodeURIComponent(match[1]!);
+
+    return match[2] === undefined
+      ? { board }
+      : { board, block: decodeURIComponent(match[2]) };
+  } catch {
+    return undefined;
+  }
+}
+
+/** A link from a block to a board or one of its blocks. */
+export interface BoardLinkRef {
+  from: BlockRef;
+  to: BoardRef;
+}
+
+/** Every board link in a document. Malformed links are skipped; writes reject them. */
+export function boardLinks(board: string, document: Block[]): BoardLinkRef[] {
+  return elements(document).flatMap((element) =>
+    element.type === "markdown"
+      ? [...markdownNodes(parseMarkdown(element.markdown))].flatMap((node) => {
+          const to =
+            node.type === "link" ? boardLink(node.url ?? "") : undefined;
+
+          return to ? [{ from: { board, block: element.id! }, to }] : [];
+        })
+      : [],
+  );
+}
+
 /** Inline trace quotes keep paragraph/list layout while using retained resources. */
 export function traceQuoteLink(
   href: string,
 ): { traceId: string; eventId: string } | undefined {
-  const match = /^review-trace:([^#]+)#(.+)$/.exec(href);
+  const match = /^whiteboard:trace\/([^#]+)#(.+)$/.exec(canonicalLink(href));
 
   return match
     ? {
@@ -215,9 +318,12 @@ export function resourceReferences(document: Block[]): Block[] {
 
     return [...markdownNodes(parseMarkdown(block.markdown))].flatMap(
       (node): Block[] => {
-        if (node.type !== "link" || !node.url?.startsWith("review-trace:"))
+        if (
+          node.type !== "link" ||
+          !canonicalLink(node.url ?? "").startsWith("whiteboard:trace/")
+        )
           return [];
-        const quote = traceQuoteLink(node.url);
+        const quote = traceQuoteLink(node.url ?? "");
 
         if (!quote) throw new ReviewInputError("Invalid trace quote link.");
 
@@ -237,7 +343,13 @@ function documentReferences(
   {
     tolerant = false,
     markdown = true,
-  }: { tolerant?: boolean; markdown?: boolean } = {},
+    repositoryId,
+  }: {
+    tolerant?: boolean;
+    markdown?: boolean;
+    /** The board's repository, which commit links read from. */
+    repositoryId?: string;
+  } = {},
 ): {
   id: string;
   source: LensSource;
@@ -274,27 +386,53 @@ function documentReferences(
       return [...markdownNodes(parseMarkdown(element.markdown))].flatMap(
         (node) => {
           if (node.type !== "link") return [];
-          const href = node.url ?? "";
+          const href = canonicalLink(node.url ?? "");
 
-          if (!/^review-source:/i.test(href)) {
+          if (!href.startsWith("whiteboard:source/")) {
             // Trace links are checked by resourceReferences.
-            if (href.startsWith("review-trace:")) return [];
+            if (href.startsWith("whiteboard:trace/")) return [];
+
+            // Board links are checked against the store on write.
+            if (href.startsWith("whiteboard:board/"))
+              return boardLink(href)
+                ? []
+                : reject(
+                    `Use whiteboard:board/<sessionId> or whiteboard:board/<sessionId>#<blockId> to link a board, in block ${element.id}.`,
+                  );
 
             if (/^(?:https?:\/\/|mailto:|#)/i.test(href)) return [];
 
             return reject(
-              `Unsupported Markdown link ${JSON.stringify(href)} in block ${element.id}. Use [label](review-source:head/path#L10-L24) or review-source:base/path#L10-L24 for repository files, or review-source:diff/path#L84-R90 across sides, with a repository-relative path and verified line numbers. External links must use https://, http://, or mailto:; document anchors use #heading.`,
+              `Unsupported Markdown link ${JSON.stringify(href)} in block ${element.id}. Use [label](whiteboard:source/head/path#L10-L24) or whiteboard:source/base/path#L10-L24 for repository files, whiteboard:source/diff/path#L84-R90 across sides, or whiteboard:source/<commit>/path#L10-L24 at a commit of the board's repository, with a repository-relative path and verified line numbers. Link another board as whiteboard:board/<sessionId>, or one of its blocks as whiteboard:board/<sessionId>#<blockId>. External links must use https://, http://, or mailto:; document anchors use #heading.`,
             );
           }
 
           let target: string;
 
           try {
-            target = decodeURIComponent(href.slice("review-source:".length));
+            target = decodeURIComponent(
+              href.slice("whiteboard:source/".length),
+            );
           } catch {
             return reject("Invalid URL encoding in source link.");
           }
 
+          // A commit of the board's repository: the commit is the link's pins.
+          const commit = commitLinkTarget(target);
+
+          if (commit)
+            return repositoryId
+              ? select(commit.anchor, {
+                  repositoryId,
+                  head: commit.commit,
+                }).map((source) => ({
+                  id: `${element.id}:${node.url}`,
+                  source,
+                }))
+              : reject(
+                  `A commit link names a commit of the board's repository, and this board has none, in block ${element.id}.`,
+                );
+
           // Links share the anchor grammar blocks use.
           const anchor = target.replace(/^(head|base|diff)\//i, (side) =>
             side.toLowerCase(),
@@ -302,7 +440,7 @@ function documentReferences(
 
           if (!parseAnchor(anchor))
             return reject(
-              "Use review-source:head/path#L10-L24 (or base, or diff/path#L84-R90 across sides) for a source link.",
+              "Use whiteboard:source/head/path#L10-L24 (or base, diff/path#L84-R90 across sides, or <commit>/path#L10-L24 at a commit of the board's repository) for a source link.",
             );
 
           return select(anchor, element.pins).map((source) => ({
@@ -414,10 +552,108 @@ function documentReferences(
 /** All authored attachments, including code peeks, select the aligned diff. */
 export const selectionReferences = documentReferences;
 
+const commitLinkDestination = linkDestination(
+  String.raw`whiteboard:source\/([0-9a-f]{7,40})\/`,
+);
+
+/** The commits a document's Markdown commit links name, as written. */
+export function commitLinkCommits(document: Block[]): string[] {
+  const commits = new Set<string>();
+
+  JSON.stringify(document, (key, value: JsonValue) => {
+    if (key === "markdown" && isStringValue(value))
+      for (const match of value.matchAll(commitLinkDestination))
+        commits.add(match[2]!);
+
+    return value;
+  });
+
+  return [...commits];
+}
+
+/** Rewrites the commits Markdown commit links name, as a short commit
+ * becomes the full one on save. */
+export function respellCommitLinks(
+  document: Block[],
+  commits: ReadonlyMap<string, string>,
+): Block[] {
+  return rewriteMarkdown(document, (markdown) =>
+    markdown.replace(
+      commitLinkDestination,
+      (link, before: string, commit: string) =>
+        `${before}whiteboard:source/${commits.get(commit) ?? commit}/`,
+    ),
+  );
+}
+
+/** Blocks that carry pins of their own for the references in them. */
+const pinnedBlockTypes = new Set([
+  "markdown",
+  "code_peek",
+  "sequence",
+  "flow_diagram",
+  "call_stack_diff",
+  "database_lens",
+]);
+
+const sideLinkDestination = linkDestination(
+  String.raw`whiteboard:source\/(head|base)\/`,
+);
+
+/**
+ * Makes every reference that reads at the document's pins carry them
+ * itself, for a board about to lose its pins: Markdown head/ and base/
+ * links become commit links, and a block whose references still lean on
+ * the document's pins (any anchor, or a diff/ link) takes them as its own.
+ * Nothing changes what it points at.
+ */
+export function pinDocumentReferences(document: Block[], pins: Pins): Block[] {
+  const own: SourcePins = {
+    repositoryId: pins.repositoryId,
+    base: pins.base,
+    head: pins.head,
+  };
+
+  const pinned = structuredClone(document);
+
+  for (const element of elements(pinned)) {
+    if (!pinnedBlockTypes.has(element.type)) continue;
+
+    // SAFETY: every pinned block type has optional source pins of its own.
+    const block = element as Block & { pins?: SourcePins };
+
+    if (block.pins) continue;
+
+    if (block.type === "markdown")
+      block.markdown = respellLinks(block.markdown).replace(
+        sideLinkDestination,
+        (_, before: string, side: string) =>
+          `${before}whiteboard:source/${side.toLowerCase() === "base" ? pins.base : pins.head}/`,
+      );
+
+    if (
+      documentReferences([block], { tolerant: true }).some(
+        (reference) => !reference.source.pins,
+      )
+    )
+      block.pins = own;
+  }
+
+  return pinned;
+}
+
+/** The repository a board's commit links read from: its target's. */
+export function boardRepositoryId(board: {
+  target?: { repositoryId: string };
+  pins?: { repositoryId: string };
+}): string | undefined {
+  return board.target?.repositoryId ?? board.pins?.repositoryId;
+}
+
 /** Per-side read coordinates for endpoint validation and retained source quotes. */
 export function sourceReferences(
   document: Block[],
-  options: { tolerant?: boolean } = {},
+  options: { tolerant?: boolean; repositoryId?: string } = {},
 ) {
   return selectionReferences(document, options).flatMap((ref) =>
     sourceAnchors(ref.source).map((source) => ({ ...ref, source })),
@@ -425,12 +661,16 @@ export function sourceReferences(
 }
 
 /** Includes lenses and maps without inline ranges. */
-export function hasCodeReferences(review: {
+/** Whether a board reads code at its own pins: a commit link or a block
+ * with pins of its own names its commits itself. */
+export function readsAtBoardPins(review: {
   document: Block[];
   lenses?: readonly Lens[];
 }): boolean {
   return Boolean(
-    sourceReferences(review.document).length ||
+    sourceReferences(review.document, { tolerant: true }).some(
+      (reference) => !reference.source.pins,
+    ) ||
     review.lenses?.length ||
     resourceReferences(review.document).some(
       (block) => block.type === "software_map",
@@ -514,6 +754,8 @@ export interface EditSummary {
   units?: string[];
   /** The agent whose courier draws this edit, when the host could tell. */
   activityId?: string;
+  /** The Ask thread that made this edit, if any. */
+  threadId?: string;
 }
 
 /** A component an edit wrote, named so the author can address it. */
@@ -711,18 +953,33 @@ export function assignFreshIds(
   element: Element,
   allocate: (prefix: string) => string,
 ): void {
-  if (element.id !== undefined)
-    throw new ReviewInputError("IDs are assigned by the server.");
-  element.id = allocate(idPrefix(element));
+  assignIds(element, allocate, true);
+}
 
-  for (const child of children(element)) assignFreshIds(child, allocate);
+/** Give ids to the parts of an element tree that have none, keeping the
+ * rest: a person's save names the blocks it kept and leaves new ones bare. */
+export function assignMissingIds(
+  element: Element,
+  allocate: (prefix: string) => string,
+): void {
+  assignIds(element, allocate, false);
+}
 
+function assignIds(
+  element: Element,
+  allocate: (prefix: string) => string,
+  fresh: boolean,
+): void {
   const assign = (item: { id?: string }, prefix: string) => {
-    if (item.id !== undefined)
+    if (item.id === undefined) item.id = allocate(prefix);
+    else if (fresh)
       throw new ReviewInputError("IDs are assigned by the server.");
-    item.id = allocate(prefix);
   };
 
+  assign(element, idPrefix(element));
+
+  for (const child of children(element)) assignIds(child, allocate, fresh);
+
   if (element.type === "call_stack_diff")
     for (const frame of [...element.base, ...element.head])
       assign(frame, "frame");
@@ -735,16 +992,10 @@ export function assignFreshIds(
     }
 }
 
-export interface ApplyEditOptions {
-  /** Where a root-level insert with no placement lands: the end by default. */
-  placement?: "first" | "last";
-}
-
 export function applyEdit(
   document: Block[],
   edit: Edit,
   allocate: (prefix: string) => string,
-  options: ApplyEditOptions = {},
 ): Applied {
   adoptFlowUnits(document, allocate);
 
@@ -808,14 +1059,10 @@ export function applyEdit(
     // Resolve the destination before detaching, then compute its final position.
     if (from) from.splice(from.indexOf(element), 1);
 
-    // A running log reads newest first, so a root insert with no placement
-    // may lead the document; a move or a unit inside a diagram never does.
     const index =
-      afterId !== undefined
-        ? siblings.findIndex((s) => s.id === afterId) + 1
-        : !parent && !from && options.placement === "first"
-          ? 0
-          : siblings.length;
+      afterId === undefined
+        ? siblings.length
+        : siblings.findIndex((s) => s.id === afterId) + 1;
 
     siblings.splice(index, 0, element);
   };