@dev.fast/whiteboard 0.3.4-preview.20261019.127 → 0.3.4

package/src/review-api/document.ts

@@ -1,8 +1,6 @@
-import { type JsonValue, isStringValue } from "@dev.fast/json";
 import {
   type Anchor,
   type LensSource,
-  commitLinkTarget,
   parseAnchor,
   selectionProblem,
   sourceAnchors,
@@ -146,11 +144,6 @@ 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,
@@ -166,16 +159,8 @@ const targets = <Repository extends Record<string, z.ZodType>>(
 
 export const reviewTargetSchema = targets({ repositoryId: 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()]),
-  }),
-]);
+/** How agents name a target: by the checkout's path, registered on acceptance. */
+export const pathTargetSchema = targets({ repositoryPath: label });
 
 export type ReviewTarget = z.infer<typeof reviewTargetSchema>;
 
@@ -190,99 +175,11 @@ 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 = /^whiteboard:trace\/([^#]+)#(.+)$/.exec(canonicalLink(href));
+  const match = /^review-trace:([^#]+)#(.+)$/.exec(href);
 
   return match
     ? {
@@ -318,12 +215,9 @@ export function resourceReferences(document: Block[]): Block[] {
 
     return [...markdownNodes(parseMarkdown(block.markdown))].flatMap(
       (node): Block[] => {
-        if (
-          node.type !== "link" ||
-          !canonicalLink(node.url ?? "").startsWith("whiteboard:trace/")
-        )
+        if (node.type !== "link" || !node.url?.startsWith("review-trace:"))
           return [];
-        const quote = traceQuoteLink(node.url ?? "");
+        const quote = traceQuoteLink(node.url);
 
         if (!quote) throw new ReviewInputError("Invalid trace quote link.");
 
@@ -343,13 +237,7 @@ function documentReferences(
   {
     tolerant = false,
     markdown = true,
-    repositoryId,
-  }: {
-    tolerant?: boolean;
-    markdown?: boolean;
-    /** The board's repository, which commit links read from. */
-    repositoryId?: string;
-  } = {},
+  }: { tolerant?: boolean; markdown?: boolean } = {},
 ): {
   id: string;
   source: LensSource;
@@ -386,53 +274,27 @@ function documentReferences(
       return [...markdownNodes(parseMarkdown(element.markdown))].flatMap(
         (node) => {
           if (node.type !== "link") return [];
-          const href = canonicalLink(node.url ?? "");
+          const href = node.url ?? "";
 
-          if (!href.startsWith("whiteboard:source/")) {
+          if (!/^review-source:/i.test(href)) {
             // Trace links are checked by resourceReferences.
-            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 (href.startsWith("review-trace:")) return [];
 
             if (/^(?:https?:\/\/|mailto:|#)/i.test(href)) return [];
 
             return reject(
-              `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.`,
+              `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.`,
             );
           }
 
           let target: string;
 
           try {
-            target = decodeURIComponent(
-              href.slice("whiteboard:source/".length),
-            );
+            target = decodeURIComponent(href.slice("review-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(),
@@ -440,7 +302,7 @@ function documentReferences(
 
           if (!parseAnchor(anchor))
             return reject(
-              "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.",
+              "Use review-source:head/path#L10-L24 (or base, or diff/path#L84-R90 across sides) for a source link.",
             );
 
           return select(anchor, element.pins).map((source) => ({
@@ -552,108 +414,10 @@ 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; repositoryId?: string } = {},
+  options: { tolerant?: boolean } = {},
 ) {
   return selectionReferences(document, options).flatMap((ref) =>
     sourceAnchors(ref.source).map((source) => ({ ...ref, source })),
@@ -661,16 +425,12 @@ export function sourceReferences(
 }
 
 /** Includes lenses and maps without inline ranges. */
-/** 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: {
+export function hasCodeReferences(review: {
   document: Block[];
   lenses?: readonly Lens[];
 }): boolean {
   return Boolean(
-    sourceReferences(review.document, { tolerant: true }).some(
-      (reference) => !reference.source.pins,
-    ) ||
+    sourceReferences(review.document).length ||
     review.lenses?.length ||
     resourceReferences(review.document).some(
       (block) => block.type === "software_map",
@@ -754,8 +514,6 @@ 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. */
@@ -953,33 +711,18 @@ export function assignFreshIds(
   element: Element,
   allocate: (prefix: string) => string,
 ): void {
-  assignIds(element, allocate, true);
-}
+  if (element.id !== undefined)
+    throw new ReviewInputError("IDs are assigned by the server.");
+  element.id = allocate(idPrefix(element));
 
-/** 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);
-}
+  for (const child of children(element)) assignFreshIds(child, allocate);
 
-function assignIds(
-  element: Element,
-  allocate: (prefix: string) => string,
-  fresh: boolean,
-): void {
   const assign = (item: { id?: string }, prefix: string) => {
-    if (item.id === undefined) item.id = allocate(prefix);
-    else if (fresh)
+    if (item.id !== undefined)
       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");
@@ -992,10 +735,16 @@ function assignIds(
     }
 }
 
+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);
 
@@ -1059,10 +808,14 @@ 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.length
-        : siblings.findIndex((s) => s.id === afterId) + 1;
+      afterId !== undefined
+        ? siblings.findIndex((s) => s.id === afterId) + 1
+        : !parent && !from && options.placement === "first"
+          ? 0
+          : siblings.length;
 
     siblings.splice(index, 0, element);
   };

package/src/review-api/github-provider.ts

@@ -1,11 +1,10 @@
 import { parseGitRemote } from "@dev.fast/local-vcs";
-import type { PullRequestState } from "@dev.fast/review-protocol";
 import { errorMessage } from "@dev.fast/trace-core";
 import { z } from "zod";
 
 import { ReviewInputError } from "./document.js";
 import type { PullRequestProvider } from "./provider.js";
-import { GitHubRefusedRead, firstLine } from "./pull-request.js";
+import { firstLine } from "./pull-request.js";
 
 const GH_TIMEOUT_MS = 20_000;
 
@@ -21,24 +20,8 @@ const metadataSchema = z.object({
   baseRefOid: z.string().optional(),
   headRefName: z.string().min(1),
   isCrossRepository: z.boolean(),
-  state: z.enum(["OPEN", "CLOSED", "MERGED"]).optional(),
-  isDraft: z.boolean().optional(),
 });
 
-/** gh's state and draft flag as one state. */
-function ghState(
-  state: "OPEN" | "CLOSED" | "MERGED" | undefined,
-  isDraft: boolean | undefined,
-): PullRequestState | undefined {
-  if (state === "MERGED") return "merged";
-
-  if (state === "CLOSED") return "closed";
-
-  if (state === "OPEN") return isDraft ? "draft" : "open";
-
-  return undefined;
-}
-
 function unreadable(url: string, ghFailure: string, fallback: string) {
   return new ReviewInputError(
     `Could not read ${url}: gh failed (${ghFailure}) and ${fallback}. Run \`gh auth status\` and sign in with an account that can read the repository, then retry.`,
@@ -71,27 +54,24 @@ export const githubProvider: PullRequestProvider = {
         [
           "pr",
           "view",
-          { value: String(number) },
+          String(number),
           "--repo",
-          { value: `${host}/${slug}` },
+          `${host}/${slug}`,
           "--json",
-          "number,title,baseRefName,baseRefOid,headRefName,isCrossRepository,state,isDraft",
+          "number,title,baseRefName,baseRefOid,headRefName,isCrossRepository",
         ],
         { timeoutMs: GH_TIMEOUT_MS },
       );
 
-      const { headRefName, isCrossRepository, state, isDraft, ...metadata } =
+      const { headRefName, isCrossRepository, ...metadata } =
         metadataSchema.parse(JSON.parse(stdout));
 
-      const pullRequestState = ghState(state, isDraft);
-
       return {
         host,
         slug,
         headRef,
         ...metadata,
         headBranch: isCrossRepository ? undefined : headRefName,
-        ...(pullRequestState && { state: pullRequestState }),
       };
     } catch (error) {
       ghFailure = firstLine(errorMessage(error));
@@ -130,21 +110,15 @@ export const githubProvider: PullRequestProvider = {
         404,
       );
 
-    if (response.status === 403 || response.status === 429) {
-      const reset = Number(response.headers.get("x-ratelimit-reset"));
-
-      throw new GitHubRefusedRead(
-        unreadable(
-          url,
-          ghFailure,
-          response.headers.get("x-ratelimit-remaining") === "0" ||
-            response.status === 429
-            ? "the unauthenticated GitHub API rate limit is exhausted"
-            : "the GitHub API refused the request",
-        ).message,
-        reset > 0 ? reset * 1000 : Date.now() + 15 * 60_000,
+    if (response.status === 403 || response.status === 429)
+      throw unreadable(
+        url,
+        ghFailure,
+        response.headers.get("x-ratelimit-remaining") === "0" ||
+          response.status === 429
+          ? "the unauthenticated GitHub API rate limit is exhausted"
+          : "the GitHub API refused the request",
       );
-    }
 
     if (!response.ok)
       throw unreadable(
@@ -166,9 +140,6 @@ export const githubProvider: PullRequestProvider = {
           ref: z.string().min(1),
           repo: z.object({ id: z.number() }).nullable(),
         }),
-        state: z.enum(["open", "closed"]).optional(),
-        draft: z.boolean().optional(),
-        merged_at: z.string().nullable().optional(),
       })
       .safeParse(await response.json().catch(() => undefined));
 
@@ -187,15 +158,6 @@ export const githubProvider: PullRequestProvider = {
         parsed.data.head.repo?.id === parsed.data.base.repo.id
           ? parsed.data.head.ref
           : undefined,
-      ...(parsed.data.state && {
-        state: parsed.data.merged_at
-          ? "merged"
-          : parsed.data.state === "closed"
-            ? "closed"
-            : parsed.data.draft
-              ? "draft"
-              : "open",
-      }),
     };
   },